reedham-aws
diff --git a/‎.coveragerc_no_lang_ext‎
Lines changed: 15 additions & 0 deletions b/‎.coveragerc_no_lang_ext‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎Makefile‎
Lines changed: 24 additions & 5 deletions b/‎Makefile‎
Lines changed: 24 additions & 5 deletions
diff --git a/‎docs/cfn-language-extensions.md‎
Lines changed: 165 additions & 0 deletions b/‎docs/cfn-language-extensions.md‎
Lines changed: 165 additions & 0 deletions
diff --git a/‎pyproject.toml‎
Lines changed: 1 addition & 0 deletions b/‎pyproject.toml‎
Lines changed: 1 addition & 0 deletions
@@ -0,0 +1,15 @@
+# Coverage config for `make test` which skips cfn_language_extensions tests.
+# Extends the base .coveragerc and also excludes the language extensions source
+# so coverage % isn't penalized when those tests are skipped.
+[run]
+branch = True
+omit =
+    samcli/lib/cfn_language_extensions/*
+    # Inherited from .coveragerc
+    samcli/lib/iac/plugins_interfaces.py
+    samcli/lib/init/templates/*
+    samcli/hook_packages/terraform/copy_terraform_built_artifacts.py
+[report]
+exclude_lines =
+    pragma: no cover
+    raise NotImplementedError.*
@@ -26,11 +26,20 @@ init-latest-release:
 	bash tests/install-sam-cli-binary.sh
 
 test:
-	# Run unit tests and fail if coverage falls below 94%
+	# Run unit tests (excluding cfn_language_extensions) and fail if coverage falls below 94%
+	@echo "NOTE: Excluding cfn_language_extensions tests. Use 'make test-all' for full coverage."
+	pytest --cov samcli --cov schema --cov-report term-missing --cov-fail-under 94 tests/unit --ignore=tests/unit/lib/cfn_language_extensions --cov-config=.coveragerc_no_lang_ext
+
+test-lang-ext:
+	# Run cfn_language_extensions unit tests with coverage
+	pytest --cov samcli.lib.cfn_language_extensions --cov-report term-missing --cov-fail-under 94 tests/unit/lib/cfn_language_extensions
+
+test-all:
+	# Run all unit tests including cfn_language_extensions
 	pytest --cov samcli --cov schema --cov-report term-missing --cov-fail-under 94 tests/unit
 
 test-cov-report:
-	# Run unit tests with html coverage report
+	# Run all unit tests with html coverage report
 	pytest --cov samcli --cov schema --cov-report html --cov-fail-under 94 tests/unit
 
 integ-test:
@@ -58,7 +67,17 @@ lint:
 	mypy --exclude /testdata/ --exclude /init/templates/ --no-incremental setup.py samcli tests schema
 
 # Command to run everytime you make changes to verify everything works
-dev: lint test
+# Runs test-all if cfn_language_extensions files changed, otherwise test
+dev: lint
+	@if git diff --name-only origin/develop... 2>/dev/null | grep -qE 'cfn_language_extensions/'; then \
+		echo "Detected cfn_language_extensions changes — running all tests"; \
+		$(MAKE) test-all; \
+	else \
+		$(MAKE) test; \
+	fi
+
+# Run full verification including language extensions tests
+dev-all: lint test-all
 
 black:
 	black setup.py samcli tests schema
@@ -72,8 +91,8 @@ format: black
 schema:
 	python -m schema.make_schema
 
-# Verifications to run before sending a pull request
-pr: init schema black-check dev
+# Verifications to run before sending a pull request — runs ALL tests
+pr: init schema black-check lint test-all
 
 # Update all reproducible requirements using uv (can run from any platform)
 update-reproducible-reqs:
 
@@ -0,0 +1,165 @@
+# CloudFormation Language Extensions Support
+
+SAM CLI now supports templates that use the `AWS::LanguageExtensions` transform, including `Fn::ForEach`, `Fn::Length`, `Fn::ToJsonString`, and `Fn::FindInMap` with `DefaultValue`.
+
+## How it works
+
+When SAM CLI detects `AWS::LanguageExtensions` in a template's `Transform` section, it expands language extension constructs locally before running SAM transforms. This enables `sam build`, `sam package`, `sam deploy`, `sam sync`, `sam validate`, `sam local invoke`, and `sam local start-api` to work with templates that use these constructs.
+
+The expansion happens in two phases:
+
+1. **Phase 1 (Language Extensions)** — `Fn::ForEach` loops are expanded, intrinsic functions are resolved where possible, and the template is converted to standard CloudFormation.
+2. **Phase 2 (SAM Transform)** — The expanded template is processed by the SAM Translator as usual.
+
+The original template (with `Fn::ForEach` intact) is preserved for CloudFormation deployment, since CloudFormation processes the `AWS::LanguageExtensions` transform server-side.
+
+## Fn::ForEach
+
+`Fn::ForEach` generates multiple resources, conditions, or outputs from a single template definition:
+
+```yaml
+Transform: AWS::LanguageExtensions
+
+Parameters:
+  ServiceNames:
+    Type: CommaDelimitedList
+    Default: "Users,Orders,Products"
+
+Resources:
+  Fn::ForEach::Services:
+    - Name
+    - !Ref ServiceNames
+    - ${Name}Function:
+        Type: AWS::Serverless::Function
+        Properties:
+          Handler: index.handler
+          Runtime: python3.12
+          CodeUri: ./services/${Name}
+```
+
+Running `sam build` expands this into `UsersFunction`, `OrdersFunction`, and `ProductsFunction`, each built from its respective source directory.
+
+### Dynamic artifact properties
+
+When a packageable property (like `CodeUri`, `ContentUri`, `ImageUri`) uses a loop variable (e.g., `./services/${Name}`), SAM CLI generates a CloudFormation `Mappings` section that maps each collection value to its S3 URI. The `Fn::ForEach` body is rewritten to use `Fn::FindInMap` so CloudFormation can resolve the correct artifact at deploy time.
+
+For example, after `sam package`:
+
+```yaml
+Mappings:
+  SAMCodeUriServices:
+    Users:
+      CodeUri: s3://my-bucket/abc123
+    Orders:
+      CodeUri: s3://my-bucket/def456
+    Products:
+      CodeUri: s3://my-bucket/ghi789
+
+Resources:
+  Fn::ForEach::Services:
+    - Name
+    - !Ref ServiceNames
+    - ${Name}Function:
+        Type: AWS::Serverless::Function
+        Properties:
+          Handler: index.handler
+          Runtime: python3.12
+          CodeUri: !FindInMap [SAMCodeUriServices, !Ref Name, CodeUri]
+```
+
+### Parameter-based collections
+
+When the `Fn::ForEach` collection is a parameter reference (`!Ref ServiceNames`), the collection values are resolved at package time from:
+
+1. `--parameter-overrides` passed to `sam build` or `sam package`
+2. The parameter's `Default` value in the template
+
+**Important:** If you change the parameter value at deploy time (e.g., adding a new service), you must re-package first so the Mappings include entries for the new values.
+
+```bash
+# Package with the values you intend to deploy with
+sam package --parameter-overrides ServiceNames="Users,Orders,Products"
+
+# Deploy with the same values
+sam deploy --parameter-overrides ServiceNames="Users,Orders,Products"
+```
+
+### Nested stacks
+
+`Fn::ForEach` in nested stack templates (`AWS::CloudFormation::Stack`) is supported. SAM CLI passes the parent stack's `Parameters` property to the child template expansion, so child `Fn::ForEach` collections that reference parent-supplied parameters resolve correctly.
+
+```yaml
+# parent.yaml
+Resources:
+  ChildStack:
+    Type: AWS::CloudFormation::Stack
+    Properties:
+      TemplateURL: ./child.yaml
+      Parameters:
+        ServiceNames: "Users,Orders,Products"
+```
+
+### Nested Fn::ForEach
+
+Up to 5 levels of nesting are supported, matching CloudFormation's limit:
+
+```yaml
+Resources:
+  Fn::ForEach::Envs:
+    - Env
+    - [Dev, Staging, Prod]
+    - Fn::ForEach::Services:
+        - Svc
+        - [Users, Orders]
+        - ${Env}${Svc}Function:
+            Type: AWS::Serverless::Function
+            Properties:
+              CodeUri: ./services/${Svc}
+              Environment:
+                Variables:
+                  STAGE: !Ref Env
+```
+
+### &{identifier} syntax
+
+The `&{identifier}` syntax strips non-alphanumeric characters from the substituted value, useful for generating valid logical IDs from values like IP addresses:
+
+```yaml
+Fn::ForEach::Hosts:
+  - IP
+  - ["10.0.0.1", "10.0.0.2"]
+  - Host&{IP}:
+      Type: AWS::EC2::Instance
+      # Expands to Host10001, Host10002
+```
+
+## Supported intrinsic functions
+
+The following intrinsic functions are resolved locally during expansion:
+
+| Function | Description |
+|----------|-------------|
+| `Fn::ForEach` | Loop expansion |
+| `Fn::Length` | Returns count of list elements |
+| `Fn::ToJsonString` | Converts value to JSON string |
+| `Fn::FindInMap` | Map lookup (with optional `DefaultValue`) |
+| `Fn::If` | Conditional value selection |
+| `Fn::Sub` | String substitution |
+| `Fn::Join` | String concatenation |
+| `Fn::Split` | String splitting |
+| `Fn::Select` | List element selection |
+| `Fn::Base64` | Base64 encoding |
+| `Fn::Equals` / `Fn::And` / `Fn::Or` / `Fn::Not` | Condition evaluation |
+| `Ref` | Parameter and pseudo-parameter references |
+
+Functions that require deployed resources (`Fn::GetAtt`, `Fn::ImportValue`, `Fn::GetAZs`) are preserved for CloudFormation to resolve at deploy time.
+
+## Limitations
+
+- **Collections must be resolvable at build/package time.** `Fn::ForEach` collections that use `Fn::GetAtt`, `Fn::ImportValue`, or SSM/Secrets Manager dynamic references cannot be expanded locally. Use a parameter with `--parameter-overrides` instead.
+- **Parameter values are fixed at package time.** If you change `--parameter-overrides` at deploy time without re-packaging, the Mappings won't include entries for new values and deployment will fail.
+- **`DeletionPolicy` and `UpdateReplacePolicy`** are validated and resolved during expansion. They support `Ref` to parameters but not other intrinsic functions.
+
+## Telemetry
+
+SAM CLI tracks usage of `AWS::LanguageExtensions` via the `CFNLanguageExtensions` telemetry feature flag. No template content is transmitted.
@@ -132,6 +132,7 @@ max-statements = 80
 "integration_uri.py" = ["E501"] # ARNs are long.
 "app.py" = ["E501"] # Doc links are long.
 
+
 [tool.black]
 line-length = 120
 target_version = ['py310', 'py311', 'py312', 'py313']