fix: share Fn::ForEach and SAM-mapping helpers across modules

Two issues flagged by the bot reviewer on PR #8637:

[BUG] _update_sam_mappings_relative_paths in samcli/commands/_utils/
template.py used mapping_name.startswith("SAM") to decide whether to
rewrite Mapping values as relative paths. That loose check corrupts
customer-authored mappings whose names happen to start with SAM as a
substring — SAMPLE, SAMSUNG, SAMCustomMapping, etc. Values would be
silently rewritten with relative-path prefixes.

[STYLE] infra_sync_executor.py had two hardcoded
resource_logical_id.startswith("Fn::ForEach::") checks instead of
using the shared is_foreach_key helper the rest of the codebase
adopted in this PR. Maintenance risk if the detection logic ever
changes.

Consolidation:
- Moved the precise SAM-mapping classifier (previously
  _is_sam_generated_mapping in samcli/commands/deploy/exceptions.py)
  into samcli/lib/cfn_language_extensions/utils.py as the public
  is_sam_generated_mapping so both deploy/exceptions.py and
  commands/_utils/template.py share the same implementation.
- _update_sam_mappings_relative_paths now calls
  is_sam_generated_mapping — SAMPLE/SAMSUNG style names are
  correctly ignored.
- infra_sync_executor.py now calls is_foreach_key at both sites.

Tests:
- test_skips_sam_prefix_substring_mappings in
  TestUpdateSamMappingsRelativePaths verifies SAMPLE/SAMSUNG/
  SAMCustomMapping are left untouched.
- Existing TestIsSamGeneratedMapping and TestCreateDeployError
  still pass via the re-export in deploy/exceptions.py.

Author: bnusunny

samcli/commands/_utils/template.py

@@ -11,7 +11,11 @@
 from botocore.utils import set_value_from_jmespath
 
 from samcli.commands.exceptions import UserException
-from samcli.lib.cfn_language_extensions.utils import FOREACH_REQUIRED_ELEMENTS, is_foreach_key
+from samcli.lib.cfn_language_extensions.utils import (
+    FOREACH_REQUIRED_ELEMENTS,
+    is_foreach_key,
+    is_sam_generated_mapping,
+)
 from samcli.lib.samlib.resource_metadata_normalizer import ASSET_PATH_METADATA_KEY, ResourceMetadataNormalizer
 from samcli.lib.utils import graphql_api
 from samcli.lib.utils.packagetype import IMAGE, ZIP
@@ -303,8 +307,11 @@ def _update_sam_mappings_relative_paths(mappings, original_root, new_root):
         return
 
     for mapping_name, mapping_entries in mappings.items():
-        # Only process SAM-generated Mappings (prefixed with "SAM")
-        if not mapping_name.startswith("SAM"):
+        # Only process SAM-generated Mappings (known PascalCase prefixes like
+        # SAMCodeUri…, SAMImageUri…, SAMLayers…). Skipping with a loose
+        # startswith("SAM") check would corrupt customer mappings that happen
+        # to share the prefix as a substring (SAMPLE, SAMSUNG, etc.).
+        if not is_sam_generated_mapping(mapping_name):
             continue
 
         if not isinstance(mapping_entries, dict):

samcli/commands/deploy/exceptions.py

@@ -20,48 +20,6 @@
     r"(?:'([^']+)'|\"([^\"]+)\"|(\S+))"
 )
 
-# Mapping-name prefixes that SAM CLI emits for dynamic Fn::ForEach handling:
-#   - SAM + <packageable artifact property> + <nesting path> + [resource suffix]
-#   - SAMLayers + <nesting path> (auto dependency layer references)
-# See language_extensions_packaging._compute_mapping_name and build_context.
-# Customer-authored mappings should never start with one of these exact
-# PascalCase prefixes, so exact-prefix matching avoids the false positives
-# a regex like r"^SAM[A-Z]..." would hit on names like "SAMPLE" / "SAMSUNG".
-_SAM_GENERATED_MAPPING_PREFIXES: Tuple[str, ...] = (
-    "SAMCodeUri",
-    "SAMImageUri",
-    "SAMContentUri",
-    "SAMDefinitionUri",
-    "SAMSchemaUri",
-    "SAMBodyS3Location",
-    "SAMDefinitionS3Location",
-    "SAMTemplateURL",
-    "SAMCode",
-    "SAMContent",
-    "SAMLayers",
-)
-
-
-def _is_sam_generated_mapping(mapping_name: str) -> bool:
-    """Check whether *mapping_name* matches the naming scheme SAM CLI uses for
-    Mappings emitted during sam build / sam package for dynamic Fn::ForEach
-    artifact properties. See language_extensions_packaging._compute_mapping_name.
-    """
-    if not mapping_name:
-        return False
-    for prefix in _SAM_GENERATED_MAPPING_PREFIXES:
-        if mapping_name == prefix:
-            # Bare prefix with no nesting path isn't a real SAM-generated name.
-            return False
-        if mapping_name.startswith(prefix):
-            # The next character must start a new PascalCase segment (upper-case
-            # letter). Digits or lower-case letters here indicate a user name
-            # that happens to share the prefix.
-            nxt = mapping_name[len(prefix)]
-            if "A" <= nxt <= "Z":
-                return True
-    return False
-
 
 def parse_findmap_error(error_message: str) -> Optional[Tuple[str, str]]:
     """

samcli/lib/cfn_language_extensions/utils.py

@@ -48,6 +48,50 @@ def is_foreach_key(key: str) -> bool:
     return isinstance(key, str) and key.startswith(FOREACH_PREFIX)
 
 
+# Mapping-name prefixes that SAM CLI emits for dynamic Fn::ForEach handling:
+#   - SAM + <packageable artifact property> + <nesting path> + [resource suffix]
+#     (see language_extensions_packaging._compute_mapping_name)
+#   - SAMLayers + <nesting path>  (see build_context — auto dependency layer refs)
+# Customer-authored mappings should never start with one of these exact
+# PascalCase prefixes, so exact-prefix matching avoids the false positives
+# a regex like r"^SAM[A-Z]..." would hit on names like SAMPLE / SAMSUNG.
+_SAM_GENERATED_MAPPING_PREFIXES: Tuple[str, ...] = (
+    "SAMCodeUri",
+    "SAMImageUri",
+    "SAMContentUri",
+    "SAMDefinitionUri",
+    "SAMSchemaUri",
+    "SAMBodyS3Location",
+    "SAMDefinitionS3Location",
+    "SAMTemplateURL",
+    "SAMCode",
+    "SAMContent",
+    "SAMLayers",
+)
+
+
+def is_sam_generated_mapping(mapping_name: str) -> bool:
+    """Return True if *mapping_name* matches the naming scheme SAM CLI uses
+    for Mappings emitted during sam build / sam package for dynamic
+    Fn::ForEach artifact properties.
+
+    Customer-authored mappings that happen to start with "SAM" as a substring
+    (e.g. SAMPLE, SAMSUNG) will NOT match because the next character after the
+    prefix must begin a new PascalCase segment (upper-case letter).
+    """
+    if not mapping_name:
+        return False
+    for prefix in _SAM_GENERATED_MAPPING_PREFIXES:
+        if mapping_name == prefix:
+            # Bare prefix with no nesting path isn't a real SAM-generated name.
+            return False
+        if mapping_name.startswith(prefix):
+            nxt = mapping_name[len(prefix)]
+            if "A" <= nxt <= "Z":
+                return True
+    return False
+
+
 def iter_regular_resources(template_dict: Dict) -> Iterator[Tuple[str, Dict]]:
     """
     Yield (logical_id, resource_dict) pairs from a template's Resources section,

samcli/lib/deploy/deployer.py

@@ -34,9 +34,9 @@
     DeployStackOutPutFailedError,
     DeployStackStatusMissingError,
     MissingMappingKeyError,
-    _is_sam_generated_mapping,
     parse_findmap_error,
 )
+from samcli.lib.cfn_language_extensions.utils import is_sam_generated_mapping
 from samcli.lib.deploy.utils import DeployColor, FailureMode
 from samcli.lib.package.local_files_utils import get_uploaded_s3_object_name, mktempfile
 from samcli.lib.package.s3_uploader import S3Uploader
@@ -123,7 +123,7 @@ def _create_deploy_error(stack_name: str, error_message: str) -> Exception:
             # failures (e.g. a RegionMap lookup) must pass through with the
             # raw CloudFormation message — the SAM-specific re-package guidance
             # would be misleading otherwise.
-            if _is_sam_generated_mapping(mapping_name):
+            if is_sam_generated_mapping(mapping_name):
                 return MissingMappingKeyError(
                     stack_name=stack_name,
                     missing_key=missing_key,

samcli/lib/sync/infra_sync_executor.py

@@ -17,6 +17,7 @@
 from samcli.commands.build.build_context import BuildContext
 from samcli.commands.deploy.deploy_context import DeployContext
 from samcli.commands.package.package_context import PackageContext
+from samcli.lib.cfn_language_extensions.utils import is_foreach_key
 from samcli.lib.providers.provider import ResourceIdentifier
 from samcli.lib.providers.sam_stack_provider import is_local_path
 from samcli.lib.telemetry.event import EventTracker
@@ -284,7 +285,7 @@ def _auto_skip_infra_sync(
 
         # The recursive template check for Nested stacks
         for resource_logical_id in current_template.get("Resources", {}):
-            if resource_logical_id.startswith("Fn::ForEach::"):
+            if is_foreach_key(resource_logical_id):
                 continue
 
             resource_dict = current_template.get("Resources", {}).get(resource_logical_id, {})
@@ -397,7 +398,7 @@ def _sanitize_template(
         built_resource_dict = None
 
         for resource_logical_id in resources:
-            if resource_logical_id.startswith("Fn::ForEach::"):
+            if is_foreach_key(resource_logical_id):
                 continue
 
             resource_dict = resources.get(resource_logical_id, {})

tests/unit/commands/_utils/test_template_language_extensions.py

@@ -118,6 +118,18 @@ def test_skips_non_sam_mappings(self):
         # Should be unchanged
         self.assertEqual(mappings["RegionMap"]["us-east-1"]["AMI"], "ami-12345")
 
+    def test_skips_sam_prefix_substring_mappings(self):
+        """User-authored mappings like SAMPLE / SAMSUNG must not be treated as SAM-generated."""
+        mappings = {
+            "SAMPLE": {"key1": {"CodeUri": "services/users"}},
+            "SAMSUNG": {"key2": {"CodeUri": "services/orders"}},
+            "SAMCustomMapping": {"key3": {"CodeUri": "services/products"}},
+        }
+        _update_sam_mappings_relative_paths(mappings, "/old", "/new")
+        self.assertEqual(mappings["SAMPLE"]["key1"]["CodeUri"], "services/users")
+        self.assertEqual(mappings["SAMSUNG"]["key2"]["CodeUri"], "services/orders")
+        self.assertEqual(mappings["SAMCustomMapping"]["key3"]["CodeUri"], "services/products")
+
     def test_skips_non_dict_mapping_entries(self):
         mappings = {"SAMCodeUriFunctions": "not a dict"}
         _update_sam_mappings_relative_paths(mappings, "/old", "/new")

tests/unit/commands/deploy/test_exceptions.py

@@ -160,7 +160,7 @@ def test_missing_mapping_key_error_explains_foreach_constraint(self):
 
 
 class TestIsSamGeneratedMapping(TestCase):
-    """Tests for the _is_sam_generated_mapping classifier.
+    """Tests for the is_sam_generated_mapping classifier.
 
     The classifier gates whether Deployer wraps a CloudFormation
     Fn::FindInMap failure as MissingMappingKeyError (which emits
@@ -170,7 +170,7 @@ class TestIsSamGeneratedMapping(TestCase):
     """
 
     def test_sam_generated_names_match(self):
-        from samcli.commands.deploy.exceptions import _is_sam_generated_mapping
+        from samcli.lib.cfn_language_extensions.utils import is_sam_generated_mapping
 
         for name in (
             "SAMCodeUriServices",
@@ -179,10 +179,10 @@ def test_sam_generated_names_match(self):
             "SAMImageUriFunctionsApi",
         ):
             with self.subTest(name=name):
-                self.assertTrue(_is_sam_generated_mapping(name))
+                self.assertTrue(is_sam_generated_mapping(name))
 
     def test_user_mapping_names_do_not_match(self):
-        from samcli.commands.deploy.exceptions import _is_sam_generated_mapping
+        from samcli.lib.cfn_language_extensions.utils import is_sam_generated_mapping
 
         for name in (
             "RegionMap",
@@ -200,9 +200,9 @@ def test_user_mapping_names_do_not_match(self):
             "",
         ):
             with self.subTest(name=name):
-                self.assertFalse(_is_sam_generated_mapping(name))
+                self.assertFalse(is_sam_generated_mapping(name))
 
     def test_none_input_is_false(self):
-        from samcli.commands.deploy.exceptions import _is_sam_generated_mapping
+        from samcli.lib.cfn_language_extensions.utils import is_sam_generated_mapping
 
-        self.assertFalse(_is_sam_generated_mapping(None))
+        self.assertFalse(is_sam_generated_mapping(None))