Add YAML 1.2 conversion foundation

[Marius Storhaug (MariusStorhaug)]

Summary

• bundle the verified YamlDotNet 18.1.0 netstandard2.0 assembly, unchanged MIT license, and third-party provenance notice
• replace the template command with ConvertFrom-Yaml, ConvertTo-Yaml, and Test-Yaml
• implement source-level YAML 1.2 core-schema construction, safe standard-tag handling, neutral unknown-tag behavior, duplicate-key rejection, multi-document streams, anchors/aliases, complex keys, and configurable resource limits
• normalize supported PowerShell values before low-level event emission, preserve repeated acyclic references, and reject cycles, unsupported objects, and mapping keys that normalize to duplicate YAML values
• adopt Process-PSModule v6.1.4, Pester 6 requirements, and important-file patterns that route src/, tests/, and README changes through the real workflow
• replace the placeholder README and example with command contracts and honest compatibility boundaries

Parser and object semantics

• implicit plain scalars use the YAML 1.2 core schema; YAML 1.1-only Boolean words and untagged timestamps remain strings
• explicit str, null, bool, int, float, binary, timestamp, seq, map, set, omap, and pairs tags are handled without reflection or type activation
• unknown application tags are discarded safely: scalars remain strings and collections retain their underlying shape
• ordinary string-key mappings become ordered PSCustomObject values; -AsHashtable returns recursive OrderedDictionary values and preserves complex keys
• structural duplicate keys are rejected with bounded SHA-256 fingerprints, including canonical numeric spellings, equivalent offset timestamps, aliases, and unordered complex mappings
• collection aliases preserve CLR reference identity where representable; cyclic parsed graphs are supported, while cyclic mapping keys are rejected
• top-level sequences enumerate by default and remain one pipeline record with -NoEnumerate; pipeline strings are joined with LF so Get-Content works

Serializer semantics

• supports PSCustomObject and explicit PSObject note-property bags, IDictionary, sequences, strings/chars, Booleans, signed and unsigned integers, BigInteger, decimal, float/double, DateTime, DateTimeOffset, enums, null, and byte arrays
• emits only a YAML 1.2-compatible subset through low-level YamlDotNet events
• emits deterministic anchors for repeated acyclic containers
• rejects cycles, unsupported runtime objects, non-data properties, normalized duplicate keys, and depth/node/scalar-limit violations instead of truncating or stringifying values
• collects multiple pipeline records into one top-level sequence

Compatibility boundaries

PowerShell values do not retain YAML presentation metadata. Data round trips therefore do not preserve comments, scalar style, tag spelling/handles, unknown application tags, anchor names, mapping presentation, line endings, or source formatting. Exact numeric CLR widths and enum CLR types are also not reconstructed. YAML merge keys are ordinary mapping data under the core schema and are not expanded.

Process-PSModule's generated-docs job is skipped because PlatyPS preloads a conflicting YamlDotNet assembly before importing this module. Public comment help remains complete and is validated by source and module linting.

Dependency provenance

• NuGet package: YamlDotNet 18.1.0
• package SHA-256: 59FFE65ADE67AD9D886267F877B634A450363CB81B94E19DB9CA4C36461416F6
• bundled asset: lib/netstandard2.0/YamlDotNet.dll
• DLL SHA-256: 91CD6D1FD0AE5B64BF6B252EB3B1AF2382CBC599C29045427C45FE8403D4295D
• source manifest intentionally omits RequiredAssemblies; Build-PSModule discovers the DLL and generates it

Test coverage

• 118 Pester 6 tests
• all 28 executable YAML 1.2.2 Chapter 2 examples, attributed to yaml/yaml-spec
• pinned offline reference cases from yaml/yaml-test-suite@da267a5c4782e7361e82889e76c0dc7df0e1e870
• focused core schema, invalid syntax, duplicate key, complex key, multi-document, alias identity, alias-DAG resource safety, depth/node/alias/scalar limits, hostile tags, PowerShell mapping, pipeline, serialization, and round-trip coverage

Validation

• Invoke-Pester -Path .\tests: 118 passed, 0 failed
• local artifact-mode Pester coverage: 77.13% against the generated Yaml.psm1
• PSScriptAnalyzer with the repository settings: clean
• all source, test, manifest, and example PowerShell files parse cleanly
• generated the module with the pinned Build-PSModule v5.0.0 action logic; local Windows execution required a session-only regex-path escaping fix in the action copy
• generated manifest contains DotNetFrameworkVersion = '4.7.2', RequiredAssemblies = 'assemblies\YamlDotNet.dll', all three exports, and a FileList containing the DLL, upstream license, notice, and root module
• source and generated DLL hashes both match 91CD6D1FD0AE5B64BF6B252EB3B1AF2382CBC599C29045427C45FE8403D4295D
• fresh PowerShell 7.6.3 and Windows PowerShell 5.1.26100.8875 imports both load YamlDotNet, complete a nested alias round trip, preserve reference identity, and consistently reject finite float overflow
• Process-PSModule passes repository lint, Build-Module, source lint/tests, built-module lint/tests, and every per-file Pester suite across Linux, macOS, and Windows
• aggregated workflow coverage: 84.11% against the 50% target

[github-actions]

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
POWERSHELL	Pass ✅
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter