feat: "cdk flags" command reports active and missing feature flags (unstable) (#699)

- Read feature flag artifacts from the Cloud Assembly
- Introduces `cdk flags`, which displays user's current feature flag
configuration in the form of a table

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

Author: vivian12300

.projenrc.ts

@@ -21,6 +21,9 @@ import { TypecheckTests } from './projenrc/TypecheckTests';
 
 const TYPESCRIPT_VERSION = '5.8';
 
+// This is a temporary aws-cdk-lib version until this PR is released: https://github.com/aws/aws-cdk/pull/34919
+const AWS_CDK_LIB_VERSION = '2.203.0';
+
 /**
  * When adding an SDK dependency for a library, use this function
  *
@@ -851,7 +854,7 @@ const toolkitLib = configureProject(
       '@smithy/util-stream',
       '@types/fs-extra',
       '@types/split2',
-      'aws-cdk-lib',
+      `aws-cdk-lib@${AWS_CDK_LIB_VERSION}`,
       'aws-sdk-client-mock',
       'aws-sdk-client-mock-jest',
       'fast-check',

packages/@aws-cdk/cli-lib-alpha/THIRD_PARTY_LICENSES

@@ -18,4 +18,5 @@ export type ToolkitAction =
 | 'metadata'
 | 'init'
 | 'migrate'
-| 'refactor';
+| 'refactor'
+| 'flags';

packages/@aws-cdk/cli-lib-alpha/package.json

@@ -1,5 +1,7 @@
 import '../private/dispose-polyfill';
 import * as path from 'node:path';
+import type { FeatureFlagReportProperties } from '@aws-cdk/cloud-assembly-schema';
+import { ArtifactType } from '@aws-cdk/cloud-assembly-schema';
 import type { TemplateDiff } from '@aws-cdk/cloudformation-diff';
 import * as cxapi from '@aws-cdk/cx-api';
 import * as chalk from 'chalk';
@@ -9,7 +11,7 @@ import { NonInteractiveIoHost } from './non-interactive-io-host';
 import type { ToolkitServices } from './private';
 import { assemblyFromSource } from './private';
 import { ToolkitError } from './toolkit-error';
-import type { DeployResult, DestroyResult, RollbackResult } from './types';
+import type { FeatureFlag, DeployResult, DestroyResult, RollbackResult } from './types';
 import type {
   BootstrapEnvironments,
   BootstrapOptions,
@@ -142,7 +144,7 @@ export interface ToolkitOptions {
  * Names of toolkit features that are still under development, and may change in
  * the future.
  */
-export type UnstableFeature = 'refactor';
+export type UnstableFeature = 'refactor' | 'flags';
 
 /**
  * The AWS CDK Programmatic Toolkit
@@ -1271,6 +1273,33 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     }
   }
 
+  /**
+   * Retrieve feature flag information from the cloud assembly
+   */
+
+  public async flags(cx: ICloudAssemblySource): Promise<FeatureFlag[]> {
+    this.requireUnstableFeature('flags');
+
+    const ioHelper = asIoHelper(this.ioHost, 'flags');
+    await using assembly = await assemblyFromSource(ioHelper, cx);
+    const artifacts = assembly.cloudAssembly.manifest.artifacts;
+
+    return Object.values(artifacts!)
+      .filter(a => a.type === ArtifactType.FEATURE_FLAG_REPORT)
+      .flatMap(report => {
+        const properties = report.properties as FeatureFlagReportProperties;
+        const moduleName = properties.module;
+
+        return Object.entries(properties.flags).map(([flagName, flagInfo]) => ({
+          module: moduleName,
+          name: flagName,
+          recommendedValue: flagInfo.recommendedValue,
+          userValue: flagInfo.userValue ?? undefined,
+          explanation: flagInfo.explanation ?? '',
+        }));
+      });
+  }
+
   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/integ-runner/THIRD_PARTY_LICENSES

@@ -116,3 +116,11 @@ export interface RolledBackStack extends PhysicalStack {
 }
 
 export type StackRollbackResult = 'rolled-back' | 'already-stable';
+
+export interface FeatureFlag {
+  readonly module: string;
+  readonly name: string;
+  readonly recommendedValue: unknown;
+  readonly userValue?: unknown;
+  readonly explanation?: string;
+}