fix(toolkit-lib): refactor feature is not marked as unstable (#563)

This introduces the concept of unstable featues to the toolkit. The CLI
always opts into it because it has its own similar flag.

Over time, the type `UnstableFeature` will change according to the
features that are unstable at the moment. All commands that are
considered unstable should call the `requireUnstableFeature` method.

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

Author: otaviomacedo

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

@@ -131,6 +131,13 @@ export interface ToolkitOptions {
    * @default - A fresh plugin host
    */
   readonly pluginHost?: PluginHost;
+
+  /**
+   * Set of unstable features to opt into. If you are using an unstable feature,
+   * you must explicitly acknowledge that you are aware of the risks of using it,
+   * by passing it in this set.
+   */
+  readonly unstableFeatures?: Array<UnstableFeature>;
 }
 
 interface StackGroup {
@@ -139,6 +146,12 @@ interface StackGroup {
   deployedStacks: CloudFormationStack[];
 }
 
+/**
+ * Names of toolkit features that are still under development, and may change in
+ * the future.
+ */
+export type UnstableFeature = 'refactor';
+
 /**
  * The AWS CDK Programmatic Toolkit
  */
@@ -165,6 +178,8 @@ export class Toolkit extends CloudAssemblySourceBuilder {
 
   private baseCredentials: IBaseCredentialsProvider;
 
+  private readonly unstableFeatures: Array<UnstableFeature>;
+
   public constructor(private readonly props: ToolkitOptions = {}) {
     super();
     this.toolkitStackName = props.toolkitStackName ?? DEFAULT_TOOLKIT_STACK_NAME;
@@ -183,6 +198,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     this.ioHost = withTrimmedWhitespace(ioHost);
 
     this.baseCredentials = props.sdkConfig?.baseCredentials ?? BaseCredentials.awsCliCompatible();
+    this.unstableFeatures = props.unstableFeatures ?? [];
   }
 
   /**
@@ -1051,6 +1067,8 @@ export class Toolkit extends CloudAssemblySourceBuilder {
    * Refactor Action. Moves resources from one location (stack + logical ID) to another.
    */
   public async refactor(cx: ICloudAssemblySource, options: RefactorOptions = {}): Promise<void> {
+    this.requireUnstableFeature('refactor');
+
     const ioHelper = asIoHelper(this.ioHost, 'refactor');
     const assembly = await assemblyFromSource(ioHelper, cx);
     return this._refactor(assembly, ioHelper, options);
@@ -1284,6 +1302,12 @@ export class Toolkit extends CloudAssemblySourceBuilder {
       // just continue - deploy will show the error
     }
   }
+
+  private requireUnstableFeature(requestedFeature: UnstableFeature) {
+    if (!this.unstableFeatures.includes(requestedFeature)) {
+      throw new ToolkitError(`Unstable feature '${requestedFeature}' is not enabled. Please enable it under 'unstableFeatures'`);
+    }
+  }
 }
 
 /**

packages/@aws-cdk/toolkit-lib/test/actions/refactor.test.ts

@@ -8,7 +8,7 @@ import { mockCloudFormationClient, MockSdk } from '../_helpers/mock-sdk';
 jest.setTimeout(10_000);
 
 const ioHost = new TestIoHost();
-const toolkit = new Toolkit({ ioHost });
+const toolkit = new Toolkit({ ioHost, unstableFeatures: ['refactor'] });
 
 jest.spyOn(SdkProvider.prototype, '_makeSdk').mockReturnValue(new MockSdk());
 
@@ -18,6 +18,19 @@ beforeEach(() => {
   mockCloudFormationClient.reset();
 });
 
+test('requires acknowledgment that the feature is unstable', async () => {
+  // GIVEN
+  const tk = new Toolkit({ ioHost /* unstable not acknowledged */ });
+  const cx = await builderFixture(tk, 'stack-with-bucket');
+
+  // WHEN
+  await expect(
+    tk.refactor(cx, {
+      dryRun: true,
+    }),
+  ).rejects.toThrow("Unstable feature 'refactor' is not enabled. Please enable it under 'unstableFeatures'");
+});
+
 test('detects the same resource in different locations', async () => {
   // GIVEN
   mockCloudFormationClient.on(ListStacksCommand).resolves({

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

@@ -179,6 +179,7 @@ export class CdkToolkit {
       emojis: true,
       ioHost: this.ioHost,
       toolkitStackName: this.toolkitStackName,
+      unstableFeatures: ['refactor'],
     });
   }