Add deterministic YAML stream formatting

[MariusStorhaug]

YAML files and generated YAML streams can accumulate inconsistent indentation, comments, flow presentation, directives, and scalar styles. Automation needs a safe way to normalize presentation without losing YAML-only representation details that cannot be projected through PowerShell objects.

Request

Desired capability

Provide a public formatter that accepts complete YAML text or line-oriented pipeline input and returns one deterministic YAML stream. Formatting must preserve document boundaries, empty documents, node kinds, scalar content, effective tags, anchors and aliases, recursive graphs, complex keys, collection structure, and mapping order.

Acceptance criteria

• Format-Yaml accepts string[] pipeline input, joins records with LF, and returns exactly one string
• Output uses explicit document starts, configurable indentation, LF line endings, and no final newline
• Comments, directives, document-end markers, flow presentation, scalar styles, and source anchor names are normalized deterministically
• Formatting is byte-idempotent at the same options
• Parser safety controls and classified YAML failures match ConvertFrom-Yaml
• The official 402-input YAML corpus verifies representation preservation, valid reparse, invalid rejection, and idempotence without changing existing corpus surfaces
• Public help, generated documentation, examples, exports, source tests, artifact tests, analysis, and site builds include the formatter

---

Technical decisions

Representation path: Parse with the repository-owned YAML parser and emit directly from the representation graph. PowerShell object projection is not used because it cannot preserve unknown tags, explicit standard tags, complex keys, empty documents, or recursive alias graphs losslessly.

Normalization: Emit deterministic block presentation with one explicit --- marker per document, canonical standard-tag shorthand where available, verbatim effective tags otherwise, and deterministic anchor renaming.

Safety and errors: Reuse parser defaults, ranges, duplicate-key policy, and classified terminating errors without broad fallback handling.

Conformance: Compare canonical representation events and node identity before and after formatting, require valid reparse and byte-identical second formatting, and classify duplicate representation-key cases from parser behavior rather than case IDs.

---

Implementation plan

Core

• Add direct representation-to-emission graph conversion
• Add deterministic effective-tag and anchor emission
• Add the public Format-Yaml advanced function and parser safety parameters
• Export the command in the generated module package

Tests

• Add focused formatter contract, normalization, graph, tag, scalar, limit, and failure tests
• Add a separate formatter surface to all 402 official corpus inputs
• Preserve existing source, artifact, file-command, and corpus surfaces
• Validate source and built artifacts on Windows, Linux, and macOS under PowerShell 7.6.x

Documentation and delivery

• Add complete comment-based help and generated command documentation
• Update the README and shipped example
• Open stacked draft pull request 🚀 [Feature]: YAML streams can now be normalized safely #42 against implement-yaml-file-io

[MariusStorhaug]

Structured the work item into the canonical three-section format and recorded the completed delivery.

• Added user-facing acceptance criteria for deterministic, representation-preserving formatting
• Documented the direct representation-emission, normalization, safety, and conformance decisions
• Marked the implementation, test, documentation, packaging, and cross-platform validation tasks complete
• Linked the stacked draft pull request