fix: Address PR aws#8299 code review feedback

Implement all 6 corrections requested by @bnusunny:

Must Fix:
1. Fix duplicate nested stack headers by using is_parent parameter
   to control header display only at top level
2. Support all AWS partitions (aws, aws-cn, aws-us-gov, aws-iso,
   aws-iso-b) in ARN parsing for nested changeset errors
3. Change return type from Union[Dict[str, List], bool] to
   Optional[Dict[str, List]] for consistency

Should Fix:
4. Add full recursion support for deeply nested stacks (3+ levels)
   with proper header display for each level
5. Implement pagination using boto3 paginators for large changesets
   to handle nested stacks with many resources

Consider:
6. Add CLI opt-out flag --include-nested-stacks/--no-include-nested-stacks
   (default: True) to allow users to disable nested stack display for
   large hierarchies

All changes include corresponding unit test updates. Integration tests
added to verify nested stack changeset display functionality.

Related: aws#2406

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: dcabib

samcli/commands/deploy/command.py

@@ -108,6 +108,15 @@
     is_flag=True,
     help="Prompt to confirm if the computed changeset is to be deployed by SAM CLI.",
 )
+@click.option(
+    "--include-nested-stacks/--no-include-nested-stacks",
+    default=True,
+    required=False,
+    is_flag=True,
+    help="Display changes for nested stacks in the changeset. "
+    "For large nested stack hierarchies, use --no-include-nested-stacks to reduce output verbosity. "
+    "Defaults to displaying nested stack changes.",
+)
 @click.option(
     "--disable-rollback/--no-disable-rollback",
     default=False,
@@ -191,6 +200,7 @@ def cli(
     metadata,
     guided,
     confirm_changeset,
+    include_nested_stacks,
     signing_profiles,
     resolve_s3,
     resolve_image_repos,
@@ -226,6 +236,7 @@ def cli(
         metadata,
         guided,
         confirm_changeset,
+        include_nested_stacks,
         ctx.region,
         ctx.profile,
         signing_profiles,
@@ -260,16 +271,17 @@ def do_cli(
     metadata,
     guided,
     confirm_changeset,
-    region,
-    profile,
-    signing_profiles,
-    resolve_s3,
-    config_file,
-    config_env,
-    resolve_image_repos,
-    disable_rollback,
-    on_failure,
-    max_wait_duration,
+    include_nested_stacks=True,
+    region=None,
+    profile=None,
+    signing_profiles=None,
+    resolve_s3=False,
+    config_file=None,
+    config_env=None,
+    resolve_image_repos=False,
+    disable_rollback=False,
+    on_failure=None,
+    max_wait_duration=60,
 ):
     """
     Implementation of the ``cli`` method
@@ -370,6 +382,7 @@ def do_cli(
             region=guided_context.guided_region if guided else region,
             profile=profile,
             confirm_changeset=guided_context.confirm_changeset if guided else confirm_changeset,
+            include_nested_stacks=include_nested_stacks,
             signing_profiles=guided_context.signing_profiles if guided else signing_profiles,
             use_changeset=True,
             disable_rollback=guided_context.disable_rollback if guided else disable_rollback,

samcli/commands/deploy/core/options.py

@@ -34,6 +34,7 @@
     "no_execute_changeset",
     "fail_on_empty_changeset",
     "confirm_changeset",
+    "include_nested_stacks",
     "disable_rollback",
     "on_failure",
     "force_upload",

samcli/commands/deploy/deploy_context.py

@@ -69,12 +69,13 @@ def __init__(
         region,
         profile,
         confirm_changeset,
-        signing_profiles,
-        use_changeset,
-        disable_rollback,
-        poll_delay,
-        on_failure,
-        max_wait_duration,
+        include_nested_stacks=True,
+        signing_profiles=None,
+        use_changeset=True,
+        disable_rollback=False,
+        poll_delay=0.5,
+        on_failure=None,
+        max_wait_duration=60,
     ):
         self.template_file = template_file
         self.stack_name = stack_name
@@ -101,6 +102,7 @@ def __init__(
         self.s3_uploader = None
         self.deployer = None
         self.confirm_changeset = confirm_changeset
+        self.include_nested_stacks = include_nested_stacks
         self.signing_profiles = signing_profiles
         self.use_changeset = use_changeset
         self.disable_rollback = disable_rollback
@@ -257,6 +259,7 @@ def deploy(
                     notification_arns=notification_arns,
                     s3_uploader=s3_uploader,
                     tags=tags,
+                    include_nested_stacks=self.include_nested_stacks,
                 )
                 click.echo(self.MSG_SHOWCASE_CHANGESET.format(changeset_id=result["Id"]))
 

samcli/commands/deploy/guided_context.py

@@ -584,6 +584,7 @@ def run(self):
                 region=self.guided_region,
                 profile=self.guided_profile,
                 confirm_changeset=self.confirm_changeset,
+                include_nested_stacks=True,
                 capabilities=self._capabilities,
                 signing_profiles=self.signing_profiles,
                 disable_rollback=self.disable_rollback,

samcli/commands/sync/command.py

@@ -394,6 +394,7 @@ def do_cli(
                     no_execute_changeset=True,
                     fail_on_empty_changeset=True,
                     confirm_changeset=False,
+                    include_nested_stacks=True,
                     use_changeset=False,
                     force_upload=True,
                     signing_profiles=None,