feat: Multi-document YAML handling (spec v0.2.9-0)

[dsillman2000]

Brings project up-to-spec with: dsillman2000/yaml-reference-specs#32 (v0.2.9-0)

PR Summary

This branch adds explicit multi-document YAML support to yaml-reference.

• !reference now rejects multi-document target files with a clear error instead of implicitly treating them like normal YAML values.
• !reference-all now expands multi-document files document-by-document, preserving file sort order and per-file document order, including anchor extraction from every document.
• Multi-document root inputs now compile to arrays, with root !ignore documents dropped while !flatten and !merge continue to compose naturally with referenced multi-document content.

Under the hood, the loader now uses an internal multi-document wrapper so it can distinguish a true multi-document file from a single YAML document whose root value happens to be a list.

The branch also adds focused unit coverage for multi-document !reference, !reference-all, anchor extraction, flattening, merging, and root-file compilation, and updates the README to document the new behavior.

[Copilot]

Pull request overview

Adds spec-compliant multi-document YAML handling to yaml-reference, extending reference resolution and root compilation semantics to properly distinguish multi-document streams from single-document sequences.

Changes:

• Introduces an internal MultiDocument wrapper and parses YAML via load_all() to support multi-document inputs.
• Updates !reference to error on multi-document targets while !reference-all expands multi-doc files document-by-document (including per-document anchor extraction).
• Adds/updates unit tests and documentation describing the new multi-document behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
yaml_reference/__init__.py	Core multi-document parsing wrapper, updated resolution + post-processing pipeline to propagate multi-docs
yaml_reference/cli.py	Improves CLI error handling for compile failures
tests/unit/test_reference.py	Adds coverage for multi-doc behavior with !reference and !reference-all
tests/unit/test_multidocument.py	New tests for multi-document root compilation semantics
tests/unit/test_flatten.py	Adds coverage for !flatten interacting with multi-doc !reference-all
tests/unit/test_merge.py	Adds coverage for !merge interacting with multi-doc !reference-all
README.md	Documents new multi-document behavior and constraints
.github/copilot-instructions.md	Updates internal project documentation to reflect supported tags and pipeline stages

---

You can also share your feedback on Copilot code review. Take the survey.