feat(globals): add per-property merge strategy for list properties

[vicheey]

Summary

Fixes #3939

Adds a per-property merge strategy to the Globals merge engine. Today, all list-type properties concatenate when both Globals and resource-level values exist. This is incorrect for properties like Architectures (a function runs on one architecture — local should replace, not append).

Changes

New module: samtranslator/plugins/globals/merge_strategy.py

• MergeOp enum: CONCATENATE, REPLACE, MERGE_BY_KEY
• MergeRule frozen dataclass with validation
• merge_by_key() factory function

Modified: samtranslator/plugins/globals/globals.py

• Path-aware recursion: _do_merge tracks the current property path through dict recursion
• Schema lookup at LIST+LIST nodes only — DICT always deep-merges, PRIMITIVE always local-wins (unchanged)
• CUSTOM_STRATEGIES dict declares per-property behavior using dot-notation paths
• _merge_by_key() method for future use (Tags merge-by-key)

Day-1 scope: Function.Architectures: REPLACE

Design

The schema uses dot-notation paths (e.g., VpcConfig.SecurityGroupIds) to support nested properties. Properties not listed in CUSTOM_STRATEGIES default to CONCATENATE — identical to today's behavior. This makes the change fully backward-compatible.

How to extend

Add entries to CUSTOM_STRATEGIES in globals.py:

CUSTOM_STRATEGIES: dict[str, MergeRule] = {
    "Function.Architectures": REPLACE,
    # Future:
    # "Function.Tags": merge_by_key("Key"),
    # "Function.VpcConfig.SecurityGroupIds": REPLACE,
}

Tests

• Unit tests for MergeRule types and validation (12 cases)
• Integration tests in GlobalPropertiesTestCases covering REPLACE, MERGE_BY_KEY, nested paths, and multi-strategy
• End-to-end translator fixture (globals_merge_strategy_architectures.yaml) proving REPLACE behavior across all 3 partitions
• All 4533 existing tests pass unchanged (backward compatibility proof)
• Coverage: 95.62%

[aws-sam-tooling-bot]

Code Review Results

Reviewed: 90ed07e..46a50d4
Files: 8
Comments: 1

[vicheey]

This PR takes inspiration from #3940 (by @allenheltondev) and expands the approach into a general-purpose framework with a strategy pattern that supports:

• REPLACE — local list wins entirely (same outcome as fix Globals.Function Architectures override behavior #3940 for Architectures)
• MERGE_BY_KEY — deduplicate list-of-dicts by a named key field (enables future Tags merge-by-key)
• Nested paths — dot-notation schema keys (e.g. VpcConfig.SecurityGroupIds) work at any depth, not just top-level

The framework is extensible via CUSTOM_STRATEGIES — adding new per-property merge behavior is a one-line dict entry rather than per-resource conditional logic.

cc @allenheltondev — thank you for the original fix and for raising #3939.

[aws-sam-tooling-bot]

Code Review Results

Reviewed: 90ed07e..69940b4
Files: 4 (source + tests; output JSON fixtures and YAML inputs are skipped)
Comments: 1