🚀 [Feature]: Preserve comments through `ConvertFrom-Yaml` → `ConvertTo-Yaml` round-trip

[MariusStorhaug]

Today ConvertFrom-Yaml discards all comments during line tokenisation, and ConvertTo-Yaml has no concept of comments to emit. A round-trip ConvertFrom-Yaml | ConvertTo-Yaml therefore loses every # comment, even though the YAML 1.2.2 spec keeps comments as a valid presentation detail.

Goal

Preserve comments across the full round-trip:

$yaml | ConvertFrom-Yaml | ConvertTo-Yaml  # comments survive

A user editing a config file via this module should not have its inline documentation silently deleted.

Why this is hard

The native PowerShell types we currently return ([PSCustomObject], [ordered] hashtable, [object[]]) cannot carry side-channel data like "the comment that appeared above this key" without a wrapper. Any solution will require one of the following design tradeoffs:

1. Custom node type — return a typed wrapper ([YamlNode] or similar) that carries content + leading/trailing comments. Breaks transparent property access ($obj.key becomes $obj.Value.key or similar).
2. Hidden metadata via PSObject.Members.Add — attach NoteProperty like __yaml_comments_<key> to existing objects. Round-trips work but pollutes the object surface and breaks anything that enumerates properties.
3. Opt-in comment-preserving mode — -PreserveComments switch that returns a richer model, default behavior unchanged. Most ergonomic.
4. Parallel comment map — ConvertFrom-Yaml -PreserveComments returns an object plus an out-of-band comment map keyed by JSON-pointer-style paths. ConvertTo-Yaml -CommentMap $map re-applies them. Cleanest separation but requires users to thread two values.

Recommend exploring (3) as the default approach with the comment storage mechanism TBD between (1) and (2).

Spec context

• Per YAML 1.2.2 §3.2.3.3: comments are a presentation detail and must not affect the serialization tree or representation graph. So preservation is a processor extension, not part of the data model — but it's a widely expected feature.
• Other YAML libraries that preserve comments: ruamel.yaml (Python), yaml-cpp, YamlDotNet round-trip mode.

Comment kinds to consider

• Leading comments above a node (most common — section headers, key documentation)
• Trailing comments on the same line as a key/value (key: value # explanation)
• Between-document comments (only relevant if multi-document support lands — see 🚀 [Feature]: Support multi-document YAML streams #21)
• Standalone comments between unrelated nodes (often just blank-line separators with text)

Acceptance criteria

• A YAML file with a representative mix of comment kinds round-trips through ConvertFrom-Yaml | ConvertTo-Yaml byte-equivalent (or content-equivalent ignoring whitespace normalisation).
• Default behavior unchanged when comment preservation is not requested.
• Spec test 2.9 (Single Document with Two Comments) passes a round-trip assertion.

Out of scope for this issue

• Implementation. This issue only tracks the design discussion and decision.
• Comment formatting normalization (e.g. enforcing a single space after #).

Related

• 🧪 Spec compliance test harness — YAML 1.2.2 Chapter 2 examples #20 (spec test harness) — once this lands, add a round-trip assertion to the relevant spec examples.
• 🚀 [Feature]: Support multi-document YAML streams #21 (multi-document streams) — comment preservation between documents depends on multi-doc support.