Align YAML directive handling with YAML 1.2.2

[MariusStorhaug]

Context

YAML 1.2.2 defines the %YAML and %TAG directives, reserves all other directives, and specifies how processors should handle version compatibility and unknown directives. Directive handling is a conformance boundary because it determines whether a document version can be processed and how tag shorthands expand.

Official YAML 1.2.2 references:

• https://yaml.org/spec/1.2.2/#681-directives
• https://yaml.org/spec/1.2.2/#6811-yaml-directives
• https://yaml.org/spec/1.2.2/#6812-tag-directives
• Repository copy: docs/yaml-spec-1.2.2/07-chapter-structural-productions/08-directives/index.md
• Normative module spec: spec/Directive-Handling.md

Current State

The module parses directive blocks, supports TAG handles, rejects malformed directives and duplicate tag handles, and rejects YAML major versions other than 1. It currently accepts every %YAML 1.x version without distinguishing YAML 1.0 from YAML 1.1/1.2/higher minor versions, and reserved directives are ignored without warning.

Objective

Make directive handling explicit, testable, and aligned with YAML 1.2.2 while preserving idiomatic PowerShell pipeline behavior.

PowerShell Design Considerations

• Warnings for accepted-but-not-exactly-1.2 documents should use normal PowerShell warning streams and must not change Boolean validation results.
• Test-Yaml should remain a clean Boolean validation surface; warnings may be observable but must not be encoded as success/failure.
• Unsupported versions should produce a stable, specific error identifier so automation can distinguish version refusal from malformed syntax.
• Parameter sets should not be added just to control directive parsing unless a future compatibility mode is introduced; default conformance should be clear.

Tasks

• Accept missing %YAML, %YAML 1.2, and %YAML 1.1 documents under YAML 1.2 processing rules.
• Accept higher minor %YAML 1.x versions with a PowerShell warning.
• Reject unsupported major versions and YAML 1.0 with a specific unsupported-version error.
• Continue rejecting duplicate %YAML directives and duplicate %TAG handles.
• Warn for syntactically valid reserved directives while ignoring their semantics.
• Keep directive blocks presentation-only for formatting and merge surfaces.

Benefits

• Aligns stream version handling with YAML 1.2.2 processor requirements.
• Gives script authors meaningful warnings without making valid documents fail validation.
• Makes future compatibility modes easier to add without changing current defaults.

Acceptance Criteria

• %YAML 1.1 parses with YAML 1.2 scalar resolution; YAML 1.1-only boolean words remain strings.
• %YAML 1.3 parses successfully and emits a warning.
• %YAML 2.0 and %YAML 1.0 terminate with an unsupported-version error.
• Reserved directives parse successfully, emit a warning, and do not affect output content.
• Test-Yaml returns $true for warning-only directive cases and $false for rejected directive cases.

Related

• Spec folder: spec/Directive-Handling.md