fix(amplify-alpha): handle empty customResponseHeaders array (#35700)

### Issue # (if applicable)

Closes #35693.

### Reason for this change

The `amplify.App` construct fails with a TypeError when `customResponseHeaders` is an empty array, preventing CDK synthesis. This is a regression introduced in v2.202.0 (PR #31771) that breaks applications passing an empty array to this property.

### Description of changes

Added defensive checks to prevent array access on empty `customResponseHeaders` arrays:

1. **Length check** in App constructor (line 319-321): Prevents calling render function with empty arrays by checking length before invocation, ensuring CloudFormation `CustomHeaders` property is properly omitted (undefined)
2. **Defensive assertion** in `renderCustomResponseHeaders` function (line 608-611): Throws clear error if function is called with empty array, catching potential CDK programming bugs
3. **JSDoc documentation** added to clarify function contract and internal nature
4. **Unit test** enhanced with clarifying comments referencing issue #35693

The fix follows CDK defensive programming patterns with a clear separation of concerns:
- **Call site validation** (line 319): Handles user input, ensures proper CloudFormation output
- **Function assertion** (line 608): Catches CDK programming errors with fail-fast behavior
- **Documentation**: Makes the contract explicit for future maintainers

### Description of how you validated changes

- **Unit tests**: Added new test case "with empty custom response headers array" that verifies empty arrays don't cause errors and that the CloudFormation `CustomHeaders` property is correctly absent. All 45 unit tests pass (100%).
- **Integration tests**: All 10 existing integration tests pass with UNCHANGED status, confirming no regression in existing functionality. The `integ.app-monorepo-custom-headers` test specifically validates custom headers behavior remains correct.
- **Manual validation**: Tested the exact reproduction case from issue #35693 - empty array no longer causes TypeError and synthesis completes successfully.

### 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: pahud

packages/@aws-cdk/aws-amplify-alpha/lib/app.ts

@@ -316,7 +316,9 @@ export class App extends Resource implements IApp, iam.IGrantable {
       name: props.appName || this.node.id,
       oauthToken: sourceCodeProviderOptions?.oauthToken?.unsafeUnwrap(), // Safe usage
       repository: sourceCodeProviderOptions?.repository,
-      customHeaders: props.customResponseHeaders ? renderCustomResponseHeaders(props.customResponseHeaders, this) : undefined,
+      customHeaders: props.customResponseHeaders && props.customResponseHeaders.length > 0
+        ? renderCustomResponseHeaders(props.customResponseHeaders, this)
+        : undefined,
       platform: appPlatform,
       jobConfig: props.buildComputeType ? { buildComputeType: props.buildComputeType } : undefined,
     });
@@ -594,7 +596,21 @@ export interface CustomResponseHeader {
   readonly headers: { [key: string]: string };
 }
 
+/**
+ * Renders custom response headers to YAML format.
+ *
+ * @param customHeaders - Array of custom headers. Must not be empty.
+ * @param scope - Construct scope for error reporting
+ * @returns YAML string representation of custom headers
+ *
+ * @internal
+ */
 function renderCustomResponseHeaders(customHeaders: CustomResponseHeader[], scope: IConstruct): string {
+  // Defensive assertion - should never happen due to call site validation
+  if (customHeaders.length === 0) {
+    throw new ValidationError('renderCustomResponseHeaders called with empty array', scope);
+  }
+
   const hasAppRoot = customHeaders[0].appRoot !== undefined;
   const yaml = [hasAppRoot ? 'applications:' : 'customHeaders:'];
 

packages/@aws-cdk/aws-amplify-alpha/test/app.test.ts

@@ -1,4 +1,4 @@
-import { Template } from 'aws-cdk-lib/assertions';
+import { Template, Match } from 'aws-cdk-lib/assertions';
 import * as codebuild from 'aws-cdk-lib/aws-codebuild';
 import * as codecommit from 'aws-cdk-lib/aws-codecommit';
 import * as iam from 'aws-cdk-lib/aws-iam';
@@ -549,6 +549,24 @@ test('error with inconsistent appRoot in custom headers', () => {
   }).toThrow('appRoot must be either be present or absent across all custom response headers');
 });
 
+test('with empty custom response headers array', () => {
+  // WHEN - Empty array should be handled gracefully (regression test for #35693)
+  new amplify.App(stack, 'App', {
+    sourceCodeProvider: new amplify.GitHubSourceCodeProvider({
+      owner: 'aws',
+      repository: 'aws-cdk',
+      oauthToken: SecretValue.unsafePlainText('secret'),
+    }),
+    customResponseHeaders: [],
+  });
+
+  // THEN - CustomHeaders property should be omitted from CloudFormation
+  Template.fromStack(stack).hasResourceProperties('AWS::Amplify::App', {
+    Name: 'App',
+    CustomHeaders: Match.absent(),
+  });
+});
+
 test('create a statically hosted app by default', () => {
   // WHEN
   new amplify.App(stack, 'App', {});