Classify timestamp boundary failures

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

src/functions/private/ConvertTo-YamlTimestampText.ps1

@@ -0,0 +1,51 @@
+function ConvertTo-YamlTimestampText {
+    <#
+        .SYNOPSIS
+        Formats a representable CLR timestamp for YAML emission.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param (
+        [Parameter(Mandatory)]
+        [object] $Value
+    )
+
+    try {
+        if ($Value -is [datetimeoffset]) {
+            $offsetMinutes = $Value.Offset.TotalMinutes
+            if ($offsetMinutes -lt -840 -or $offsetMinutes -gt 840 -or
+                $offsetMinutes -ne [System.Math]::Truncate($offsetMinutes) -or
+                $Value.UtcTicks -lt [datetime]::MinValue.Ticks -or
+                $Value.UtcTicks -gt [datetime]::MaxValue.Ticks) {
+                throw [System.ArgumentOutOfRangeException]::new('Value')
+            }
+            return $Value.ToString(
+                'o',
+                [System.Globalization.CultureInfo]::InvariantCulture
+            )
+        }
+
+        if ($Value.Kind -eq [System.DateTimeKind]::Local) {
+            return [datetimeoffset]::new($Value).ToString(
+                'o',
+                [System.Globalization.CultureInfo]::InvariantCulture
+            )
+        }
+
+        $utc = if ($Value.Kind -eq [System.DateTimeKind]::Utc) {
+            $Value
+        } else {
+            [datetime]::SpecifyKind($Value, [System.DateTimeKind]::Utc)
+        }
+        return $utc.ToString(
+            "yyyy-MM-dd'T'HH:mm:ss.fffffff'Z'",
+            [System.Globalization.CultureInfo]::InvariantCulture
+        )
+    } catch [System.ArgumentException] {
+        throw (New-YamlSerializationException -ErrorId 'YamlTimestampSerializationFailed' `
+                -Message 'The timestamp cannot be represented with its local or explicit UTC offset.')
+    } catch [System.FormatException] {
+        throw (New-YamlSerializationException -ErrorId 'YamlTimestampSerializationFailed' `
+                -Message 'The timestamp cannot be represented with its local or explicit UTC offset.')
+    }
+}

src/functions/private/Get-YamlSerializationShape.ps1

@@ -162,29 +162,14 @@ function Get-YamlSerializationShape {
     }
     if (-not $isPropertyBag -and $Value -is [datetimeoffset]) {
         $scalar.Tag = 'tag:yaml.org,2002:timestamp'
-        $scalar.Value = $Value.ToString('o', [System.Globalization.CultureInfo]::InvariantCulture)
+        $scalar.Value = ConvertTo-YamlTimestampText -Value $Value
         $scalar.Style = 'DoubleQuoted'
         Confirm-YamlScalarLength -Node $scalar -State $State
         return [pscustomobject]@{ Kind = 'Scalar'; Node = $scalar; Values = $null }
     }
     if (-not $isPropertyBag -and $Value -is [datetime]) {
         $scalar.Tag = 'tag:yaml.org,2002:timestamp'
-        if ($Value.Kind -eq [System.DateTimeKind]::Local) {
-            $scalar.Value = ([datetimeoffset] $Value).ToString(
-                'o',
-                [System.Globalization.CultureInfo]::InvariantCulture
-            )
-        } else {
-            $utc = if ($Value.Kind -eq [System.DateTimeKind]::Utc) {
-                $Value
-            } else {
-                [datetime]::SpecifyKind($Value, [System.DateTimeKind]::Utc)
-            }
-            $scalar.Value = $utc.ToString(
-                "yyyy-MM-dd'T'HH:mm:ss.fffffff'Z'",
-                [System.Globalization.CultureInfo]::InvariantCulture
-            )
-        }
+        $scalar.Value = ConvertTo-YamlTimestampText -Value $Value
         $scalar.Style = 'DoubleQuoted'
         Confirm-YamlScalarLength -Node $scalar -State $State
         return [pscustomobject]@{ Kind = 'Scalar'; Node = $scalar; Values = $null }

tests/ConvertTo-Yaml.Tests.ps1

@@ -211,6 +211,57 @@ Describe 'ConvertTo-Yaml' {
             [Text.Encoding]::UTF8.GetString($result['binary']) | Should -Be 'hello'
         }
 
+        It 'serializes every representable DateTimeOffset boundary stably' {
+            $values = @(
+                [datetimeoffset]::MinValue
+                [datetimeoffset]::MaxValue
+                [datetimeoffset]::new(
+                    [datetime]::new(1, 1, 1, 14, 0, 0),
+                    [timespan]::FromHours(14)
+                )
+                [datetimeoffset]::new(
+                    [datetime]::new(9999, 12, 31, 9, 59, 59, 999).AddTicks(9999),
+                    [timespan]::FromHours(-14)
+                )
+            )
+
+            foreach ($value in $values) {
+                $yaml = ConvertTo-Yaml -InputObject $value
+                $roundTrip = $yaml | ConvertFrom-Yaml
+
+                ($yaml | Test-Yaml) | Should -BeTrue
+                $roundTrip.UtcTicks | Should -Be $value.UtcTicks
+            }
+        }
+
+        It 'classifies unrepresentable local DateTime boundaries' {
+            $errors = [System.Collections.Generic.List[object]]::new()
+            $successes = 0
+            foreach ($value in @(
+                    [datetime]::SpecifyKind([datetime]::MinValue, [DateTimeKind]::Local)
+                    [datetime]::SpecifyKind([datetime]::MaxValue, [DateTimeKind]::Local)
+                )) {
+                try {
+                    $yaml = ConvertTo-Yaml -InputObject $value
+                    ($yaml | Test-Yaml) | Should -BeTrue
+                    $successes++
+                } catch {
+                    $errors.Add($_)
+                }
+            }
+
+            ($successes + $errors.Count) | Should -Be 2
+            if ([TimeZoneInfo]::Local.BaseUtcOffset -ne [timespan]::Zero) {
+                $errors.Count | Should -BeGreaterThan 0
+            }
+            foreach ($serializationError in $errors) {
+                $serializationError.FullyQualifiedErrorId |
+                    Should -Be 'YamlTimestampSerializationFailed,ConvertTo-Yaml'
+                $serializationError.Exception.Message |
+                    Should -Be 'The timestamp cannot be represented with its local or explicit UTC offset.'
+            }
+        }
+
         It 'emits aliases for repeated byte arrays and preserves their identity' {
             $bytes = [Text.Encoding]::UTF8.GetBytes('hello')
             $inputObject = [ordered]@{ first = $bytes; second = $bytes }