fix(package): process AWS::Include before language-extension expansion (#9027)

Closes #9027.

Symptom: when a template uses both Transform: AWS::LanguageExtensions and
contains Fn::Transform: AWS::Include buried inside an LE function (e.g.
Fn::ToJsonString), sam package fails to rewrite the include's Location to
an S3 URL. CloudFormation then rejects the deploy with 'The location
parameter is not a valid S3 uri.'

Root cause: PackageContext._export ran expand_language_extensions BEFORE
the artifact exporter walked Fn::Transform nodes. LE functions like
Fn::ToJsonString json.dumps() their argument, collapsing the structural
Fn::Transform subtree into a JSON-string literal. By the time the
exporter ran, the include was no longer a structural dict node and was
invisible to the global-transform walker.

Fix: process AWS::Include (and any other GLOBAL_TRANSFORM_EXPORTS
handler) on the original template BEFORE LE expansion runs, mirroring
CloudFormation's own server-side transform ordering — CFN resolves
inline Fn::Transform macros before evaluating AWS::LanguageExtensions.

Implementation:

- Extract Template._export_global_artifacts to a module-level
  _export_global_artifacts_pass(template_dict, uploader, template_dir).
  The instance method becomes a one-line delegate so existing callers
  keep working.
- Call _export_global_artifacts_pass on the original template before
  expand_language_extensions in PackageContext._export (root flow) and
  in CloudFormationStackResource.do_export (nested-stack child flow).

Dynamic-Location AWS::Include inside Fn::ForEach (e.g.
Location: ./swagger-${Name}.yaml) is not supported by sam package: a
local file path with literal ${...} placeholders does not exist on disk,
so is_local_file fails and the existing InvalidLocalPathError fires —
which is the right user-facing failure. CloudFormation does not
substitute loop variables into Fn::Transform paths server-side either,
so the limitation matches CFN's actual capability.

Author: bnusunny

samcli/commands/package/package_context.py

@@ -26,15 +26,15 @@
 from samcli.commands.package.exceptions import PackageFailedError
 from samcli.lib.bootstrap.companion_stack.companion_stack_manager import sync_ecr_stack
 from samcli.lib.intrinsic_resolver.intrinsics_symbol_table import IntrinsicsSymbolTable
-from samcli.lib.package.artifact_exporter import Template
+from samcli.lib.package.artifact_exporter import Template, _export_global_artifacts_pass
 from samcli.lib.package.code_signer import CodeSigner
 from samcli.lib.package.ecr_uploader import ECRUploader
 from samcli.lib.package.language_extensions_packaging import (
     generate_and_apply_artifact_mappings,
     merge_language_extensions_s3_uris,
 )
 from samcli.lib.package.s3_uploader import S3Uploader
-from samcli.lib.package.uploaders import Uploaders
+from samcli.lib.package.uploaders import Destination, Uploaders
 from samcli.lib.providers.provider import ResourceIdentifier, Stack, get_resource_full_path_by_id
 from samcli.lib.providers.sam_stack_provider import SamLocalStackProvider
 from samcli.lib.utils.boto_utils import get_boto_config_with_user_agent
@@ -177,6 +177,23 @@ def _export(self, template_path, use_json):
         with open(template_path, "r", encoding="utf-8") as f:
             original_template_dict = yaml_parse(f.read())
 
+        # Process AWS::Include (and other global Fn::Transform exporters) on the
+        # original template before language-extension expansion. This mirrors
+        # CloudFormation's server-side transform ordering and prevents LE
+        # functions like Fn::ToJsonString from collapsing structural Fn::Transform
+        # nodes into JSON-string literals before the exporter can reach them.
+        # See aws/aws-sam-cli#9027.
+        #
+        # NOTE: this mutates original_template_dict in place. The mutation must
+        # happen before expand_language_extensions snapshots the tree, so both
+        # result.original_template and result.expanded_template see the rewrite.
+        template_dir = os.path.dirname(os.path.abspath(template_path))
+        _export_global_artifacts_pass(
+            original_template_dict,
+            self.uploaders.get(Destination.S3),
+            template_dir,
+        )
+
         # Build combined parameter values for expand_language_extensions
         parameter_values = {}
         parameter_values.update(IntrinsicsSymbolTable.DEFAULT_PSEUDO_PARAM_VALUES)

samcli/lib/package/artifact_exporter.py

@@ -17,7 +17,7 @@
 import copy
 import logging
 import os
-from typing import Dict, List, Optional, Sequence
+from typing import Any, Dict, List, Optional, Sequence, cast
 
 from botocore.utils import set_value_from_jmespath
 
@@ -119,6 +119,46 @@ def _resolve_nested_stack_parameters(nested_params: Dict, parent_parameter_value
     return resolved
 
 
+def _export_global_artifacts_pass(template_dict: Any, uploader, template_dir: str) -> Any:
+    """
+    Walk template_dict recursively, dispatching dict nodes to handlers
+    registered in GLOBAL_TRANSFORM_EXPORTS (today: AWS::Include).
+
+    Mutates template_dict in place AND returns it for caller convenience.
+
+    This is the standalone form of Template._export_global_artifacts —
+    used by callers that need to run the global-transform export pass
+    on a template before constructing a Template (e.g., the pre-LE
+    pass that processes AWS::Include before language-extension
+    expansion runs).
+
+    No-ops on non-dict input (e.g. yaml_parse returning None for empty
+    template files), so callers can pass the result of yaml_parse
+    unconditionally.
+    """
+    if not isinstance(template_dict, dict):
+        return template_dict
+
+    specs_by_key: Dict[str, list] = {}
+    for spec in GLOBAL_TRANSFORM_EXPORTS:
+        specs_by_key.setdefault(spec.template_key, []).append(spec)
+
+    for key, val in template_dict.items():
+        if key in specs_by_key:
+            current = val
+            for spec in specs_by_key[key]:
+                if spec.discriminator(current):
+                    template_dict[key] = spec.handler(current, uploader, template_dir)
+                    current = template_dict[key]
+        elif isinstance(val, dict):
+            _export_global_artifacts_pass(val, uploader, template_dir)
+        elif isinstance(val, list):
+            for item in val:
+                if isinstance(item, dict):
+                    _export_global_artifacts_pass(item, uploader, template_dir)
+    return template_dict
+
+
 class CloudFormationStackResource(ResourceZip):
     """
     Represents CloudFormation::Stack resource that can refer to a nested
@@ -168,6 +208,18 @@ def do_export(self, resource_id, resource_dict, parent_dir):
 
         child_template_dir = os.path.dirname(abs_template_path)
 
+        # Process AWS::Include before LE expansion to mirror CFN's transform
+        # ordering. See aws/aws-sam-cli#9027.
+        #
+        # NOTE: mutates child_template_dict in place. Must run before the
+        # expand_language_extensions call below so result.original_template
+        # and result.expanded_template both observe the rewrite.
+        _export_global_artifacts_pass(
+            child_template_dict,
+            self.uploaders.get(ResourceZip.EXPORT_DESTINATION),
+            child_template_dir,
+        )
+
         # Merge pseudo-parameters with:
         #  1) values propagated from the parent Template (parent stack's own params
         #     + CLI --parameter-overrides + pseudo-params), used to resolve intrinsics
@@ -403,31 +455,18 @@ def __init__(
         self.parameter_values = parameter_values
 
     def _export_global_artifacts(self, template_dict: Dict) -> Dict:
+        """See module-level _export_global_artifacts_pass for the canonical
+        implementation. This wrapper exists so Template.export() doesn't
+        need to know about uploader / template_dir plumbing.
         """
-        Template params such as AWS::Include transforms are not specific to
-        any resource type but contain artifacts that should be exported,
-        here we iterate through the template dict and dispatch to handlers
-        declared in GLOBAL_TRANSFORM_EXPORTS.
-        """
-        specs_by_key: Dict[str, list] = {}
-        for spec in GLOBAL_TRANSFORM_EXPORTS:
-            specs_by_key.setdefault(spec.template_key, []).append(spec)
-
-        for key, val in template_dict.items():
-            if key in specs_by_key:
-                for spec in specs_by_key[key]:
-                    if spec.discriminator(val):
-                        template_dict[key] = spec.handler(
-                            val, self.uploaders.get(ResourceZip.EXPORT_DESTINATION), self.template_dir
-                        )
-                        val = template_dict[key]  # subsequent specs see the rewrite
-            elif isinstance(val, dict):
-                self._export_global_artifacts(val)
-            elif isinstance(val, list):
-                for item in val:
-                    if isinstance(item, dict):
-                        self._export_global_artifacts(item)
-        return template_dict
+        result = _export_global_artifacts_pass(
+            template_dict,
+            self.uploaders.get(ResourceZip.EXPORT_DESTINATION),
+            self.template_dir,
+        )
+        # template_dict is guaranteed to be a dict here, so the pass returns
+        # the same dict back. cast() narrows the return type for mypy.
+        return cast(Dict, result)
 
     def _export_metadata(self):
         """