feat: allow filtering cdk flags feature flags by substring (#776)

This allows users to run `cdk flags` with a substring and all matching
feature flags will be displayed to them.

When a user runs `cdk flags #substring#` and there is only one matching
flag, a description of the flag will be displayed. If there are multiple
matching flags, all matching flags will be displayed in a table.

If a user runs `cdk flags` with multiple substrings, all matching flags
that contain any of the substrings will be displayed in 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

packages/aws-cdk/lib/commands/flag-operations.ts

@@ -22,11 +22,23 @@ interface FlagOperationsParams {
   flagData: FeatureFlag[];
   toolkit: Toolkit;
   ioHelper: IoHelper;
+
+  /** User ran --recommended option */
   recommended?: boolean;
+
+  /** User ran --all option */
   all?: boolean;
+
+  /** User provided --value field */
   value?: string;
+
+  /** User provided FLAGNAME field */
   flagName?: string[];
+
+  /** User ran --default option */
   default?: boolean;
+
+  /** User ran --unconfigured option */
   unconfigured?: boolean;
 }
 
@@ -392,57 +404,35 @@ function formatTable(headers: string[], rows: string[][]): string {
   return table;
 }
 
-export async function displayFlags(params: FlagOperationsParams): Promise<void> {
-  const { flagData, ioHelper, flagName, all } = params;
-  if (flagName && flagName.length > 0) {
-    const flag = flagData.find(f => f.name === flagName![0]);
-    if (!flag) {
-      await ioHelper.defaults.error('Flag not found.');
-      return;
-    }
-
-    await ioHelper.defaults.info(`Description: ${flag.explanation}`);
-    await ioHelper.defaults.info(`Recommended value: ${flag.recommendedValue}`);
-    await ioHelper.defaults.info(`User value: ${flag.userValue}`);
-    return;
+function getFlagSortOrder(flag: FeatureFlag): number {
+  if (flag.userValue === undefined) {
+    return 3;
+  } else if (isUserValueEqualToRecommended(flag)) {
+    return 1;
+  } else {
+    return 2;
   }
+}
 
+async function displayFlagTable(flags: FeatureFlag[], ioHelper: IoHelper): Promise<void> {
   const headers = ['Feature Flag Name', 'Recommended Value', 'User Value'];
-  const rows: string[][] = [];
-
-  const getFlagPriority = (flag: FeatureFlag): number => {
-    if (flag.userValue === undefined) {
-      return 3;
-    } else if (isUserValueEqualToRecommended(flag)) {
-      return 1;
-    } else {
-      return 2;
-    }
-  };
-
-  let flagsToDisplay: FeatureFlag[];
-  if (all) {
-    flagsToDisplay = flagData;
-  } else {
-    flagsToDisplay = flagData.filter(flag =>
-      flag.userValue === undefined || !isUserValueEqualToRecommended(flag),
-    );
-  }
 
-  const sortedFlags = [...flagsToDisplay].sort((a, b) => {
-    const priorityA = getFlagPriority(a);
-    const priorityB = getFlagPriority(b);
+  const sortedFlags = [...flags].sort((a, b) => {
+    const orderA = getFlagSortOrder(a);
+    const orderB = getFlagSortOrder(b);
 
-    if (priorityA !== priorityB) {
-      return priorityA - priorityB;
+    if (orderA !== orderB) {
+      return orderA - orderB;
     }
     if (a.module !== b.module) {
       return a.module.localeCompare(b.module);
     }
     return a.name.localeCompare(b.name);
   });
 
+  const rows: string[][] = [];
   let currentModule = '';
+
   sortedFlags.forEach((flag) => {
     if (flag.module !== currentModule) {
       rows.push([chalk.bold(`Module: ${flag.module}`), '', '']);
@@ -459,6 +449,45 @@ export async function displayFlags(params: FlagOperationsParams): Promise<void>
   await ioHelper.defaults.info(formattedTable);
 }
 
+export async function displayFlags(params: FlagOperationsParams): Promise<void> {
+  const { flagData, ioHelper, flagName, all } = params;
+
+  if (flagName && flagName.length > 0) {
+    const matchingFlags = flagData.filter(f =>
+      flagName.some(searchTerm => f.name.toLowerCase().includes(searchTerm.toLowerCase())),
+    );
+
+    if (matchingFlags.length === 0) {
+      await ioHelper.defaults.error(`Flag matching "${flagName.join(', ')}" not found.`);
+      return;
+    }
+
+    if (matchingFlags.length === 1) {
+      const flag = matchingFlags[0];
+      await ioHelper.defaults.info(`Flag name: ${flag.name}`);
+      await ioHelper.defaults.info(`Description: ${flag.explanation}`);
+      await ioHelper.defaults.info(`Recommended value: ${flag.recommendedValue}`);
+      await ioHelper.defaults.info(`User value: ${flag.userValue}`);
+      return;
+    }
+
+    await ioHelper.defaults.info(`Found ${matchingFlags.length} flags matching "${flagName.join(', ')}":`);
+    await displayFlagTable(matchingFlags, ioHelper);
+    return;
+  }
+
+  let flagsToDisplay: FeatureFlag[];
+  if (all) {
+    flagsToDisplay = flagData;
+  } else {
+    flagsToDisplay = flagData.filter(flag =>
+      flag.userValue === undefined || !isUserValueEqualToRecommended(flag),
+    );
+  }
+
+  await displayFlagTable(flagsToDisplay, ioHelper);
+}
+
 function isUserValueEqualToRecommended(flag: FeatureFlag): boolean {
   return String(flag.userValue) === String(flag.recommendedValue);
 }

packages/aws-cdk/test/commands/flag-operations.test.ts

@@ -180,6 +180,66 @@ describe('displayFlags', () => {
     expect(plainTextOutput).toContain('aws-cdk-lib');
     expect(plainTextOutput).toContain('different-module');
   });
+
+  test('displays single flag details when only one substring match is found', async () => {
+    const params = {
+      flagData: mockFlagsData,
+      toolkit: createMockToolkit(),
+      ioHelper,
+      flagName: ['s3'],
+    };
+    await displayFlags(params);
+
+    const plainTextOutput = output();
+    expect(plainTextOutput).toContain('Description: Another test flag');
+    expect(plainTextOutput).toContain('Recommended value: false');
+    expect(plainTextOutput).toContain('User value: undefined');
+    expect(plainTextOutput).not.toContain('Found');
+    expect(plainTextOutput).not.toContain('matching');
+  });
+
+  test('returns "Flag not found" if user enters non-matching substring', async () => {
+    const params = {
+      flagData: mockFlagsData,
+      toolkit: createMockToolkit(),
+      ioHelper,
+      flagName: ['qwerty'],
+    };
+    await displayFlags(params);
+
+    const plainTextOutput = output();
+    expect(plainTextOutput).toContain('Flag matching \"qwerty\" not found.');
+  });
+
+  test('returns all matching flags if user enters common substring', async () => {
+    const params = {
+      flagData: mockFlagsData,
+      toolkit: createMockToolkit(),
+      ioHelper,
+      flagName: ['flag'],
+    };
+    await displayFlags(params);
+
+    const plainTextOutput = output();
+    expect(plainTextOutput).toContain('@aws-cdk/core:testFlag');
+    expect(plainTextOutput).toContain('@aws-cdk/s3:anotherFlag');
+    expect(plainTextOutput).toContain('@aws-cdk/core:matchingFlag');
+  });
+
+  test('returns all matching flags if user enters multiple substrings', async () => {
+    const params = {
+      flagData: mockFlagsData,
+      toolkit: createMockToolkit(),
+      ioHelper,
+      flagName: ['matching', 'test'],
+    };
+    await displayFlags(params);
+
+    const plainTextOutput = output();
+    expect(plainTextOutput).toContain('@aws-cdk/core:testFlag');
+    expect(plainTextOutput).toContain('@aws-cdk/core:matchingFlag');
+    expect(plainTextOutput).not.toContain('@aws-cdk/s3:anotherFlag');
+  });
 });
 
 describe('handleFlags', () => {
@@ -228,7 +288,7 @@ describe('handleFlags', () => {
     await handleFlags(mockFlagsData, ioHelper, options, mockToolkit);
 
     const plainTextOutput = output();
-    expect(plainTextOutput).toContain('Flag not found.');
+    expect(plainTextOutput).toContain('Flag matching \"@aws-cdk/core:nonExistentFlag\" not found.');
   });
 
   test('calls prototypeChanges when set option is true with valid flag', async () => {