what

Implements the !append YAML function that allows fine-grained control over list merging behavior in Atmos stack configurations
Lists tagged with !append will be concatenated with base values instead of replaced
Adds comprehensive unit tests and integration test fixtures

why

Resolves the ongoing challenge of needing to concatenate lists on a case-by-case basis
Currently, users have to fall back to using maps instead of lists when they need append behavior
This is particularly important for fields like depends_on where appending is often the desired behavior rather than replacement
The !append tag provides opt-in, per-field control that works alongside the global list_merge_strategy setting

Key Features

Opt-in behavior: Only lists explicitly tagged with !append use append mode
Works alongside global settings: The !append tag works independently of the global list_merge_strategy setting
Nested support: Works with deeply nested configurations
Backward compatible: No impact on existing configurations without the tag

Example Usage

# base.yaml
components:
  terraform:
    eks:
      settings:
        depends_on:
          - vpc
          - iam-role

# override.yaml
components:
  terraform:
    eks:
      settings:
        depends_on: !append  # This tag indicates append mode
          - rds
          - elasticache
          
# Result: depends_on = [vpc, iam-role, rds, elasticache]

Testing

✅ All unit tests pass
✅ Build succeeds without errors
✅ Linting passes with no issues
✅ Code follows Atmos conventions and patterns

references

Closes #2980
Linear issue: DEV-2980

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Added support for a !append YAML function to append items to lists during configuration merging (per-field, preserves order, works with nested structures and global list-merge strategies).
Tests
- Added unit tests for append-tag utilities and merge behavior, plus integration-style test cases and expected results demonstrating !append semantics.
Documentation
- Added docs and examples explaining !append usage, behavior, and interactions with existing merge settings.

Sep 25 '25 05:09 osterman

📝 Walkthrough

Walkthrough

Adds per-field YAML !append handling: YAML loader records tagged sequences as append-wrapped values; merge pre-processing consumes those wrappers to concatenate lists into merged maps. New helpers, tests, docs, test fixtures, a CLI test helper, and one new exported error were added. No public API signatures were changed.

Changes

Cohort / File(s)	Summary
YAML processing `pkg/config/process_yaml.go`	Decode YAML sequence nodes tagged `!append`, decode each list item, wrap with append metadata and store in Viper at the current path, then clear the node tag to avoid re-processing.
Merge logic `pkg/merge/merge.go`	Add pre-merge pass `processAppendTags` that walks input maps, detects append-wrapped lists and nested maps, and merges/concatenates lists into the running merged map before the normal merge flow. New internal helpers: `processAppendTags`, `processValue`, `processAppendList`, `processNestedMap`. No change to public Merge signature.
Merge tests `pkg/merge/merge_append_test.go`	New unit tests for per-field `!append` semantics and interaction with a global list-merge strategy across multiple input documents.
Append utilities `pkg/utils/yaml_func_append.go`, `pkg/utils/yaml_utils.go`	New helpers and constant: `ProcessAppendTag`, `IsAppendTag`, `HasAppendTag`, `ExtractAppendListValue`, `WrapWithAppendTag`; `AtmosYamlFuncAppend = "!append"`.
Utility tests `pkg/utils/yaml_func_append_test.go`	Unit tests for tag detection, presence checks, extraction, wrapping, and `ProcessAppendTag` validation.
E2E test cases `tests/test-cases/append-function/base.yaml`, `tests/test-cases/append-function/override-with-append.yaml`, `tests/test-cases/append-function/expected-result.yaml`	Added base config, override using `!append`, and expected merged result demonstrating appended lists.
Docs `website/docs/functions/yaml/append.mdx`, `website/docs/functions/yaml/index.mdx`	New documentation and examples describing `!append` usage, semantics, and interaction with global list merge strategies.
Errors `errors/errors.go`	Added exported error `ErrRefusingToDeleteSymlink = errors.New("refusing to delete symbolic link")`.
Test harness `tests/cli_test.go`	Added `validateAtmosBinary(repoRoot string) (string, string)` and integrated it into `TestMain` to surface a skip reason or the binary path for CLI-related tests.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant YAML as YAML Loader
  participant PY as process_yaml.go
  participant U as utils (append helpers)
  participant V as Viper (config store)

  YAML->>PY: Parse node
  alt node is sequence with tag "!append"
    PY->>PY: Decode each list item
    PY->>U: WrapWithAppendTag(items)
    U-->>PY: {"__atmos_append__": items}
    PY->>V: Set(path, wrappedValue)
    PY->>PY: Clear node.Tag
  else other node
    PY->>V: Set(path, decoded value)
  end

sequenceDiagram
  autonumber
  participant M as MergeWithOptions
  participant P as processAppendTags
  participant U as utils (append helpers)
  participant S as MergedState

  M->>P: Pre-process input map
  loop each key,value
    P->>P: processValue(key, value)
    alt value is append-wrapped list
      P->>U: ExtractAppendListValue(value)
      U-->>P: items
      P->>S: Append items into S[key] (create if missing)
    else value is nested map
      P->>P: processAppendTags(nestedMap)
      P->>S: Merge/assign nested map into S[key]
    else
      P->>S: Assign/override S[key] = value
    end
  end
  M->>M: Continue normal merge flow with processed map

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

cloudposse/atmos#1506 — modifies YAML custom-tag handling and clears node tags after processing; strongly related to the !append tag implementation.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The PR also adds an unrelated file-operation error constant (`ErrRefusingToDeleteSymlink`) and CLI binary validation logic in tests/cli_test.go, which are not part of the `!append` feature scope defined in DEV-2980.	Please remove or relocate the new symlink error constant and CLI test helper changes into a separate pull request so that this PR focuses solely on the `!append` YAML functionality.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title clearly and concisely describes the primary purpose of the changeset, which is adding the `!append` YAML function for list concatenation, matching the main feature implemented in the pull request.
Linked Issues Check	✅ Passed	The pull request fully implements the per-field `!append` tag mechanism described in DEV-2980 by detecting and wrapping append-tagged lists in the YAML parser, merging them correctly in the merge logic, providing utility helpers and unit tests, and documenting usage, all of which satisfy the linked issue’s requirements.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Sep 25 '25 05:09 coderabbitai[bot]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 72.84%. Comparing base (8e75aa1) to head (3e8e709).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1513      +/-   ##
==========================================
+ Coverage   72.81%   72.84%   +0.02%     
==========================================
  Files         530      531       +1     
  Lines       50667    50715      +48     
==========================================
+ Hits        36892    36941      +49     
+ Misses      11002    11000       -2     
- Partials     2773     2774       +1

Flag	Coverage Δ
unittests	`72.84% <100.00%> (+0.02%)`	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
errors/errors.go	`100.00% <ø> (ø)`
pkg/merge/merge.go	`86.71% <100.00%> (+1.49%)`	:arrow_up:
pkg/utils/yaml_func_append.go	`100.00% <100.00%> (ø)`
pkg/utils/yaml_utils.go	`81.10% <ø> (ø)`

... and 2 files with indirect coverage changes

:rocket: New features to boost your workflow:

:snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sep 25 '25 05:09 codecov[bot]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏

Sep 26 '25 13:09 mergify[bot]

Dec 08 '25 21:12 mergify[bot]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏

Dec 08 '25 21:12 mergify[bot]

Dec 08 '25 21:12 github-actions[bot]

Dec 08 '25 21:12 github-actions[bot]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏

Dec 09 '25 04:12 mergify[bot]

Dec 09 '25 04:12 github-actions[bot]

Dec 09 '25 18:12 github-actions[bot]

Dec 17 '25 15:12 github-actions[bot]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏

Dec 18 '25 18:12 mergify[bot]

Dec 18 '25 18:12 github-actions[bot]

Dec 22 '25 20:12 mergify[bot]

Dependency Review

The following issues were found:

✅ 0 vulnerable package(s)
❌ 3 package(s) with incompatible licenses
❌ 1 package(s) with invalid SPDX license definitions
⚠️ 7 package(s) with unknown licenses.

See the Details below.

License Issues

website/pnpm-lock.yaml

Package	Version	License	Issue Type
dompurify	3.3.1	(Apache-2.0 AND GPL-2.0-only AND MPL-2.0 AND MS-PL) OR (Apache-2.0 AND GPL-2.0-only AND MPL-2.0)	Incompatible License
node-forge	1.3.3	(BSD-3-Clause AND GPL-1.0-or-later AND GPL-2.0 AND GPL-2.0-only) OR (BSD-3-Clause AND GPL-1.0-or-later AND GPL-2.0-only)	Incompatible License
sax	1.4.3	BlueOak-1.0.0	Incompatible License
posthog-js	1.302.2	SEE LICENSE IN LICENSE	Invalid SPDX License
@csstools/postcss-position-area-property	1.0.0	Null	Unknown License
@csstools/postcss-system-ui-font-family	1.0.0	Null	Unknown License
@docsearch/core	4.3.1	Null	Unknown License
@ai-sdk/gateway	2.0.18	Null	Unknown License
@ai-sdk/react	2.0.109	Null	Unknown License
@posthog/core	1.7.1	Null	Unknown License
ai	5.0.108	Null	Unknown License

Scanned Files

website/pnpm-lock.yaml

Dec 22 '25 20:12 github-actions[bot]

feat: implement !append YAML function for list concatenation

what

why

Key Features

Example Usage

Testing

references

Summary by CodeRabbit

Rate limit exceeded

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Pre-merge checks and finishing touches

Codecov Report

This PR exceeds the recommended limit of 1,000 lines.

Changelog Entry Required

Changelog Entry Required

Changelog Entry Required

Changelog Entry Required

Changelog Entry Required

Changelog Entry Required

This PR exceeds the recommended limit of 1,000 lines.

Dependency Review

License Issues

website/pnpm-lock.yaml

Scanned Files