Add representation-preserving YAML stream merging

[MariusStorhaug]

Configuration authors need to combine layered YAML streams without losing representation details such as tags, complex keys, anchors, aliases, recursive graphs, or mapping order.

Request

Desired capability

Add Merge-Yaml so two or more complete YAML streams can be merged deterministically. Later streams have higher precedence, document counts must match, and the result is one normalized YAML 1.2 stream.

Acceptance criteria

• Accept two or more complete YAML streams through -InputObject [string[]] or the pipeline; each array element or pipeline record is one stream.
• Merge documents pairwise by zero-based document index and reject empty streams or differing positive document counts with classified errors.
• Merge compatible mappings recursively by YAML structural key equality while retaining base entry order and appending new overlay keys.
• Support Replace, Append, and Unique sequence policies; Replace and Error conflict policies; and Replace and Ignore null policies.
• Preserve selected representation nodes, standard and unknown tags, complex keys, anchors, aliases, repeated nodes, cycles, and ordinary << mapping data without object projection or YAML 1.1 merge expansion.
• Enforce parser, cloning, equality, merge, and result resource budgets.
• Emit exactly one deterministic LF-only YAML string with no final newline.
• Include complete help, README and example usage, package export and generated documentation coverage, built-artifact tests, and corpus-backed smoke coverage.

---

Technical decisions

Representation model: Parse each stream with the repository-owned parser and operate directly on representation graphs. Never project through PSCustomObject or dictionaries and never duplicate parser logic.

Graph handling: Clone selected nodes with source-node memoization and fresh output node IDs. Preserve alias and repeated-node identity, including recursive graphs, while leaving every parsed input immutable.

Mapping keys: Use deterministic structural fingerprints only to select candidate buckets, then require collision-safe graph-aware deep equality. Retain an existing key and its position when matched; append genuinely new overlay keys in overlay order.

Tags and conflicts: Compare effective tags before recursive mapping or sequence handling. Equal nodes retain the existing representation. Kind, scalar, or effective-tag differences use -ConflictAction.

Nulls and sequences: Apply -NullAction whenever the later existing value is YAML null, including document roots. Apply -SequenceAction only to compatible-tag sequences.

Safety: Mirror parser limit defaults and ranges on Merge-Yaml; apply limits during parsing, cloning, equality and merge work, and final graph validation. Surface stable YAML-classified terminating errors.

Delivery: Build on and target format-yaml. Keep the pull request in draft through local and Process-PSModule validation on PowerShell 7.6 across Windows, Linux, and macOS.

---

Implementation plan

• Add the Merge-Yaml public contract and complete comment-based help.
• Add graph-aware clone, equality, mapping, sequence, null, conflict, path, and limit helpers.
• Add table-driven source tests for policy combinations, multi-document streams, complex keys, tags, aliases, sharing, cycles, errors, limits, determinism, and self-parse.
• Add corpus-backed representation merge smoke cases.
• Update README, examples, package exports, generated documentation, and built-artifact tests.
• Run full source and artifact Pester, analyzer, parser and corpus checks, module build, docs/site build, and Process-PSModule cross-platform CI.

[MariusStorhaug]

Corrected the work item to the delegated Merge-Yaml scope.nn- Replaced the stale Remove-YamlEntry request with the representation-preserving stream merge contractn- Recorded mapping, sequence, conflict, null, graph, resource-budget, test, documentation, and stacked-delivery decisionsn- Replaced the implementation checklist so issue 43 remains the source of truth for this change

[MariusStorhaug]

Completed the implementation plan and delivery validation.nn- Added the public representation-preserving merge command, graph helpers, documentation, package export, and built-artifact coveragen- Completed the table-driven policy, graph, multi-document, resource-limit, deterministic, and corpus smoke matrixn- Passed source and built-artifact Pester, source and module lint, generated docs/site builds, and Process-PSModule on Windows, Linux, and macOSn- Delivery remains in draft PR #45 targeting format-yaml`