feat: support dynamic artifact properties in nested Fn::ForEach blocks

Make detection, build output, and package output recursive so that
dynamic artifact properties (e.g., CodeUri: ./services/${Service})
inside nested Fn::ForEach blocks are correctly handled with Mappings
transformation.

Changes:
- Add outer_loops field to DynamicArtifactProperty for tracking
  enclosing ForEach loops
- Make detect_foreach_dynamic_properties() recursive with outer_loops
  parameter to detect dynamic properties at any nesting depth
- Make _update_foreach_artifact_paths() (build) recursive with
  outer_context parameter; extract helper methods to satisfy ruff
  PLR0912 branch limit
- Make _update_foreach_with_s3_uris() (package) recursive for nested
  ForEach blocks
- Update _generate_artifact_mappings() to support compound keys when
  property references both outer and inner loop variables
- Update _replace_dynamic_artifact_with_findmap() to traverse through
  outer_loops chain to locate nested ForEach body
- Add unit tests, property tests, and integration tests
- Update spec (Requirement 25, Tasks 38-43)

Author: bnusunny

samcli/commands/build/build_context.py

@@ -497,17 +497,18 @@ def _update_original_template_paths(self, original_template: Dict, modified_temp
             original_template["Mappings"].update(all_generated_mappings)
 
     def _update_foreach_artifact_paths(
-        self, foreach_key: str, foreach_value: list, modified_resources: Dict, original_dir
+        self,
+        foreach_key: str,
+        foreach_value: list,
+        modified_resources: Dict,
+        original_dir,
+        outer_context: Optional[List[Tuple[str, List[str]]]] = None,
     ) -> Dict[str, Dict[str, Dict[str, str]]]:
         """
         Update artifact paths in a Fn::ForEach construct.
 
-        For Fn::ForEach with static CodeUri, all generated functions share the same
-        artifact path. We find one of the expanded functions and use its path.
-
-        For Fn::ForEach with dynamic CodeUri (containing the loop variable), we generate
-        a Mappings section that maps each collection value to its expanded resource's
-        build artifact path, and replace the dynamic property with Fn::FindInMap.
+        Recurses into nested Fn::ForEach blocks, passing outer loop context so that
+        expanded resource names can be fully resolved.
 
         Parameters
         ----------
@@ -519,6 +520,8 @@ def _update_foreach_artifact_paths(
             The expanded resources with updated artifact paths
         original_dir : pathlib.Path
             The directory containing the original template
+        outer_context : list of tuples, optional
+            Enclosing loop variables and their collections for nested ForEach.
 
         Returns
         -------
@@ -529,92 +532,160 @@ def _update_foreach_artifact_paths(
 
         generated_mappings: Dict[str, Dict[str, Dict[str, str]]] = {}
 
+        if outer_context is None:
+            outer_context = []
+
         if not isinstance(foreach_value, list) or len(foreach_value) < FOREACH_REQUIRED_ELEMENTS:
             return generated_mappings
 
-        # Fn::ForEach structure: [loop_var, collection, body]
         loop_variable = foreach_value[0]
         collection = foreach_value[1]
         body = foreach_value[2]
 
         if not isinstance(loop_variable, str) or not isinstance(body, dict):
             return generated_mappings
 
-        # Resolve collection values
         collection_values: List[str] = []
         if isinstance(collection, list):
             collection_values = [str(item) for item in collection if item is not None]
 
-        # Extract loop name from foreach_key
         loop_name = foreach_key.replace("Fn::ForEach::", "")
+        current_outer_context = outer_context + [(loop_variable, collection_values)]
 
-        # The body contains resource definitions with ${loop_var} placeholders
         for resource_template_key, resource_template in body.items():
+            if isinstance(resource_template_key, str) and resource_template_key.startswith("Fn::ForEach::"):
+                nested_mappings = self._update_foreach_artifact_paths(
+                    resource_template_key,
+                    resource_template,
+                    modified_resources,
+                    original_dir,
+                    outer_context=current_outer_context,
+                )
+                generated_mappings.update(nested_mappings)
+                continue
+
             if not isinstance(resource_template, dict):
                 continue
 
             resource_type = resource_template.get("Type", "")
             properties = resource_template.get("Properties", {})
-
             if not isinstance(properties, dict):
                 continue
 
-            # Check if this is a packageable resource type
-            artifact_props = PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.get(resource_type, [])
-
-            for prop_name in artifact_props:
+            for prop_name in PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.get(resource_type, []):
                 prop_value = properties.get(prop_name)
                 if prop_value is None:
                     continue
 
-                is_dynamic = self._contains_loop_variable(prop_value, loop_variable)
+                if self._contains_loop_variable(prop_value, loop_variable) and collection_values:
+                    mapping_entries = self._collect_dynamic_mapping_entries(
+                        resource_template_key,
+                        prop_name,
+                        loop_variable,
+                        collection_values,
+                        modified_resources,
+                        outer_context,
+                    )
+                    if mapping_entries:
+                        mapping_name = f"SAM{prop_name}{loop_name}"
+                        generated_mappings[mapping_name] = mapping_entries
+                        properties[prop_name] = {"Fn::FindInMap": [mapping_name, {"Ref": loop_variable}, prop_name]}
+                else:
+                    self._copy_static_artifact_property(properties, prop_name, resource_type, modified_resources)
+
+        return generated_mappings
+
+    def _collect_dynamic_mapping_entries(
+        self,
+        resource_template_key: str,
+        prop_name: str,
+        loop_variable: str,
+        collection_values: List[str],
+        modified_resources: Dict,
+        outer_context: List[Tuple[str, List[str]]],
+    ) -> Dict[str, Dict[str, str]]:
+        """
+        Collect Mapping entries for a dynamic artifact property by looking up
+        expanded resources in modified_resources.
+
+        For nested ForEach, enumerates all outer value combinations to find
+        the fully-expanded resource name.
+        """
+        mapping_entries: Dict[str, Dict[str, str]] = {}
+
+        for coll_value in collection_values:
+            if outer_context:
+                self._collect_nested_mapping_entry(
+                    resource_template_key,
+                    prop_name,
+                    loop_variable,
+                    coll_value,
+                    modified_resources,
+                    outer_context,
+                    mapping_entries,
+                )
+            else:
+                expanded_key = self._substitute_loop_variable(resource_template_key, loop_variable, coll_value)
+                artifact_value = self._get_artifact_value(modified_resources, expanded_key, prop_name)
+                if artifact_value is not None:
+                    mapping_entries[coll_value] = {prop_name: artifact_value}
 
-                if is_dynamic and collection_values:
-                    # Dynamic artifact property — generate Mappings
-                    mapping_name = f"SAM{prop_name}{loop_name}"
-                    mapping_entries: Dict[str, Dict[str, str]] = {}
+        return mapping_entries
 
-                    for coll_value in collection_values:
-                        # Find the expanded resource name
-                        expanded_key = self._substitute_loop_variable(resource_template_key, loop_variable, coll_value)
-                        modified_resource = modified_resources.get(expanded_key, {})
-                        if not isinstance(modified_resource, dict):
-                            continue
+    def _collect_nested_mapping_entry(
+        self,
+        resource_template_key: str,
+        prop_name: str,
+        loop_variable: str,
+        coll_value: str,
+        modified_resources: Dict,
+        outer_context: List[Tuple[str, List[str]]],
+        mapping_entries: Dict[str, Dict[str, str]],
+    ) -> None:
+        """Enumerate outer value combinations to find expanded resource for a nested ForEach."""
+        import itertools
 
-                        modified_props = modified_resource.get("Properties", {})
-                        if not isinstance(modified_props, dict):
-                            continue
+        outer_collections = [oc[1] for oc in outer_context]
+        outer_vars = [oc[0] for oc in outer_context]
 
-                        artifact_value = modified_props.get(prop_name)
-                        if artifact_value is not None:
-                            mapping_entries[coll_value] = {prop_name: artifact_value}
+        for outer_combo in itertools.product(*outer_collections):
+            expanded_key = resource_template_key
+            for ovar, oval in zip(outer_vars, outer_combo):
+                expanded_key = self._substitute_loop_variable(expanded_key, ovar, oval)
+            expanded_key = self._substitute_loop_variable(expanded_key, loop_variable, coll_value)
 
-                    if mapping_entries:
-                        generated_mappings[mapping_name] = mapping_entries
-                        # Replace the dynamic property with Fn::FindInMap
-                        # Use {"Ref": loop_variable} so ForEach substitutes the collection value
-                        # into the FindInMap lookup (bare ${Var} strings are NOT resolved by
-                        # ForEach inside FindInMap arguments)
-                        properties[prop_name] = {
-                            "Fn::FindInMap": [
-                                mapping_name,
-                                {"Ref": loop_variable},
-                                prop_name,
-                            ]
-                        }
-                else:
-                    # Static artifact property — copy from first matching expanded resource
-                    for modified_key, modified_resource in modified_resources.items():
-                        if not isinstance(modified_resource, dict):
-                            continue
-                        if modified_resource.get("Type", "") != resource_type:
-                            continue
-                        modified_props = modified_resource.get("Properties", {})
-                        if prop_name in modified_props:
-                            properties[prop_name] = modified_props[prop_name]
-                            break
+            artifact_value = self._get_artifact_value(modified_resources, expanded_key, prop_name)
+            if artifact_value is not None and coll_value not in mapping_entries:
+                mapping_entries[coll_value] = {prop_name: artifact_value}
 
-        return generated_mappings
+    @staticmethod
+    def _get_artifact_value(modified_resources: Dict, expanded_key: str, prop_name: str) -> Optional[Any]:
+        """Extract an artifact property value from an expanded resource, or return None."""
+        modified_resource = modified_resources.get(expanded_key, {})
+        if not isinstance(modified_resource, dict):
+            return None
+        modified_props = modified_resource.get("Properties", {})
+        if not isinstance(modified_props, dict):
+            return None
+        return modified_props.get(prop_name)
+
+    @staticmethod
+    def _copy_static_artifact_property(
+        properties: Dict,
+        prop_name: str,
+        resource_type: str,
+        modified_resources: Dict,
+    ) -> None:
+        """Copy a static artifact property from the first matching expanded resource."""
+        for modified_resource in modified_resources.values():
+            if not isinstance(modified_resource, dict):
+                continue
+            if modified_resource.get("Type", "") != resource_type:
+                continue
+            modified_props = modified_resource.get("Properties", {})
+            if prop_name in modified_props:
+                properties[prop_name] = modified_props[prop_name]
+                break
 
     @staticmethod
     def _contains_loop_variable(value: Any, loop_variable: str) -> bool: