test: validate gc command rejects --role-arn flag

Add unit test to ensure gc command throws error when used with --role-arn. Add documentation to explain reasoning behind this feature

Author: gandhya

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

@@ -477,6 +477,8 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
         if (!configuration.settings.get(['unstable']).includes('gc')) {
           throw new ToolkitError('Unstable feature use: \'gc\' is unstable. It must be opted in via \'--unstable\', e.g. \'cdk gc --unstable=gc\'');
         }
+        // roleArn is defined for when cloudformation is invoked
+        // This conflicts with direct sdk calls existing in the gc command to s3 and ecr
         if (args.roleArn) {
           throw new ToolkitError('The --role-arn option is not supported for the gc command');
         }

packages/aws-cdk/test/cli/cli.test.ts

@@ -51,6 +51,14 @@ jest.mock('../../lib/cli/parse-command-line-arguments', () => ({
       if (args.includes('ts')) {
         result = { ...result, language: 'typescript' };
       }
+    } else if (args.includes('gc')) {
+      result = { ...result, _: ['gc'] };
+
+      // Handle role-arn flag for gc command validation testing
+      // This simulates parser behavior to test that the CLI properly rejects roleArn
+      if (args.includes('--role-arn')) {
+        result = { ...result, roleArn: 'arn:aws:iam::123456789012:role/TestRole' };
+      }
     }
 
     // Handle notices flags
@@ -433,6 +441,9 @@ describe('gc command validation tests', () => {
     jest.clearAllMocks();
   });
 
+  /**
+   * Tests that the gc does not support roleArn
+   */
   test('should throw error when --role-arn is provided with gc command', async () => {
     // Mock configuration to include 'gc' in unstable features
     const mockConfig = {
@@ -450,7 +461,7 @@ describe('gc command validation tests', () => {
 
     (Configuration as any).mockImplementation(() => mockConfig);
     Configuration.fromArgsAndFiles = jest.fn().mockImplementation(() => mockConfig);
-
+    // Expects an error to be thrown when roleArn is used with gc
     await expect(exec(['gc', '--role-arn', 'arn:aws:iam::123456789012:role/TestRole', '--unstable=gc']))
       .rejects
       .toThrow('The --role-arn option is not supported for the gc command');