fix FindMatchingPeriodValue: add left-contains-right branch for retro payrun (NovaTechRetro bug)

Author: Jani Giannoudis

Client.Scripting.Tests/CasePayrollValueTests.cs

@@ -0,0 +1,149 @@
+/* CasePayrollValueTests */
+
+using System;
+using Xunit;
+
+namespace PayrollEngine.Client.Scripting.Tests;
+
+/// <summary>
+/// Tests for CasePayrollValue binary operators, focusing on
+/// FindMatchingPeriodValue period-matching behaviour.
+///
+/// NovaTechRetro bug:
+///   In a Retro-Payrun the left PeriodValue carries an open-ended Period
+///   (End = Date.MaxValue), while the right PeriodValue carries a trimmed
+///   CalendarPeriod (End = last hour of the month).
+///   The original containment check only tested whether the RIGHT period
+///   contains the LEFT period — the inverse case (open LEFT contains trimmed
+///   RIGHT) was not handled, so FindMatchingPeriodValue returned null,
+///   the operator loop silently skipped every period, and the Payrun
+///   failed with "Missing results".
+/// </summary>
+public class CasePayrollValueTests
+{
+    // ── Shared period fixtures ──────────────────────────────────────────────
+
+    /// <summary>Standard CalendarPeriod: January 2024, trimmed end (last full hour)</summary>
+    private static readonly DateTime Jan2024Start = new(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+    private static readonly DateTime Jan2024End   = new(2024, 1, 31, 23, 0, 0, DateTimeKind.Utc);
+
+    // ── 1. Exact match ──────────────────────────────────────────────────────
+
+    [Fact(DisplayName = "Operator + exact period match returns correct sum")]
+    public void Add_ExactPeriodMatch_ReturnsSum()
+    {
+        // Both sides carry identical CalendarPeriods → exact Equals() match.
+        var left  = MakeCaseValue("Salary", Jan2024Start, Jan2024End, 3000M);
+        var right = MakeCaseValue("Bonus",  Jan2024Start, Jan2024End, 500M);
+
+        decimal result = left + right;
+
+        Assert.Equal(3500M, result);
+    }
+
+    // ── 2. Normal containment (right contains left) ─────────────────────────
+
+    [Fact(DisplayName = "Operator + right-contains-left: open right covers trimmed left")]
+    public void Add_RightContainsLeft_ReturnsSum()
+    {
+        // left  = trimmed CalendarPeriod  (End = Jan2024End)
+        // right = open-ended Period        (End = Date.MaxValue)
+        // The existing containment branch handles this case.
+        var left  = MakeCaseValue("Salary", Jan2024Start, Jan2024End,   3000M);
+        var right = MakeCaseValue("Salary", Jan2024Start, null,          500M); // open-ended
+
+        decimal result = left + right;
+
+        Assert.Equal(3500M, result);
+    }
+
+    // ── 3. NovaTechRetro bug – left contains right ──────────────────────────
+
+    [Fact(DisplayName = "NovaTechRetro bug: Operator + open left vs. trimmed right returns correct sum")]
+    public void Add_OpenLeftVsTrimmedRight_RetroScenario_ReturnsSum()
+    {
+        // This is the exact scenario that caused the NovaTechRetro failure.
+        //
+        // In a Retro-Payrun, the current-period case value is delivered with an
+        // open-ended Period (End = Date.MaxValue), while the previously calculated
+        // value still carries the trimmed CalendarPeriod end.
+        //
+        // left  = open-ended Period  (End = Date.MaxValue)   ← Retro-Payrun result
+        // right = CalendarPeriod     (End = Jan2024End)      ← prior calculation
+        //
+        // Without the fix: FindMatchingPeriodValue returns null → operator skips
+        //   the period → result stays Empty → PayrollException: Missing results.
+        // With the fix: left-contains-right branch matches → result = 3000 + 100 = 3100.
+
+        var left  = MakeCaseValue("Salary", Jan2024Start, null,        3000M); // open-ended
+        var right = MakeCaseValue("Salary", Jan2024Start, Jan2024End,   100M); // CalendarPeriod
+
+        decimal result = left + right;
+
+        Assert.Equal(3100M, result);
+    }
+
+    [Fact(DisplayName = "NovaTechRetro bug: Operator - open left vs. trimmed right returns correct difference")]
+    public void Subtract_OpenLeftVsTrimmedRight_RetroScenario_ReturnsDifference()
+    {
+        // Subtraction variant: retro diff = current salary – previously calculated salary.
+        var left  = MakeCaseValue("Salary", Jan2024Start, null,        3000M);
+        var right = MakeCaseValue("Salary", Jan2024Start, Jan2024End,  2800M);
+
+        decimal result = left - right;
+
+        Assert.Equal(200M, result);
+    }
+
+    [Fact(DisplayName = "NovaTechRetro bug: Operator * open left vs. trimmed right returns correct product")]
+    public void Multiply_OpenLeftVsTrimmedRight_RetroScenario_ReturnsProduct()
+    {
+        var left  = MakeCaseValue("Rate",  Jan2024Start, null,       3000M);
+        var right = MakeCaseValue("Factor", Jan2024Start, Jan2024End,  0.1M);
+
+        decimal result = left * right;
+
+        Assert.Equal(300M, result);
+    }
+
+    [Fact(DisplayName = "NovaTechRetro bug: Operator / open left vs. trimmed right returns correct quotient")]
+    public void Divide_OpenLeftVsTrimmedRight_RetroScenario_ReturnsQuotient()
+    {
+        var left  = MakeCaseValue("Salary", Jan2024Start, null,       3000M);
+        var right = MakeCaseValue("Divisor", Jan2024Start, Jan2024End,    3M);
+
+        decimal result = left / right;
+
+        Assert.Equal(1000M, result);
+    }
+
+    // ── 4. No-match → empty result ──────────────────────────────────────────
+
+    [Fact(DisplayName = "Operator + non-overlapping periods returns empty")]
+    public void Add_NonOverlappingPeriods_ReturnsEmpty()
+    {
+        // Completely different periods → no match expected from any branch.
+        var feb2024Start = new DateTime(2024, 2, 1, 0, 0, 0, DateTimeKind.Utc);
+        var feb2024End   = new DateTime(2024, 2, 29, 23, 0, 0, DateTimeKind.Utc);
+
+        var left  = MakeCaseValue("Salary", Jan2024Start, Jan2024End, 3000M);
+        var right = MakeCaseValue("Salary", feb2024Start, feb2024End, 500M);
+
+        var result = left + right;
+
+        Assert.False(result.HasValue);
+    }
+
+    // ── Helper ──────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates a CasePayrollValue with a single PeriodValue.
+    /// When <paramref name="end"/> is null the period is open-ended (End = Date.MaxValue).
+    /// </summary>
+    private static CasePayrollValue MakeCaseValue(
+        string caseFieldName, DateTime start, DateTime? end, decimal value)
+    {
+        var periodValue = new PeriodValue(start, end, value);
+        return new CasePayrollValue(caseFieldName, [periodValue]);
+    }
+}

Client.Scripting/CasePayrollValue.cs

@@ -210,14 +210,25 @@ public static implicit operator DateTime(CasePayrollValue payrollValue) =>
     #region Binary operators
 
     /// <summary>Find the best matching period value for a given left period.
-    /// First tries exact match; falls back to containment (right period contains left period).
-    /// Required when TimeType differs, e.g. CalendarPeriod (trimmed) vs. Period (open-ended, End=MaxValue).</summary>
+    /// Tries in order: (1) exact match, (2) right contains left, (3) left contains right.
+    /// The third branch is required for Retro-Payruns where the left side carries an open-ended
+    /// Period (End=MaxValue) and the right side carries a trimmed CalendarPeriod end.
+    /// Without it, the containment check "trimmedEnd >= MaxValue" silently returns null,
+    /// causing all binary operators to return Empty and the payrun to fail with Missing results.
+    /// </summary>
     private static PeriodValue FindMatchingPeriodValue(ReadOnlyCollection<PeriodValue> periodValues, DatePeriod leftPeriod)
     {
+        // 1. exact match
         var match = periodValues.FirstOrDefault(x => Equals(x.Period, leftPeriod));
         if (match != null) return match;
-        return periodValues.FirstOrDefault(x =>
+        // 2. right contains left (open-ended right covers trimmed CalendarPeriod left)
+        match = periodValues.FirstOrDefault(x =>
             x.Period.Start <= leftPeriod.Start && x.Period.End >= leftPeriod.End);
+        if (match != null) return match;
+        // 3. left contains right (open-ended left covers trimmed CalendarPeriod right)
+        //    NovaTechRetro bug: leftPeriod = open Period (End=MaxValue), x.Period = CalendarPeriod
+        return periodValues.FirstOrDefault(x =>
+            leftPeriod.Start <= x.Period.Start && leftPeriod.End >= x.Period.End);
     }
 
     /// <summary>Addition of two case values</summary>

Client.Scripting/PayrollEngine.Client.Scripting.xml

@@ -351,8 +351,12 @@
         </member>
         <member name="M:PayrollEngine.Client.Scripting.CasePayrollValue.FindMatchingPeriodValue(System.Collections.ObjectModel.ReadOnlyCollection{PayrollEngine.Client.Scripting.PeriodValue},PayrollEngine.Client.Scripting.DatePeriod)">
             <summary>Find the best matching period value for a given left period.
-            First tries exact match; falls back to containment (right period contains left period).
-            Required when TimeType differs, e.g. CalendarPeriod (trimmed) vs. Period (open-ended, End=MaxValue).</summary>
+            Tries in order: (1) exact match, (2) right contains left, (3) left contains right.
+            The third branch is required for Retro-Payruns where the left side carries an open-ended
+            Period (End=MaxValue) and the right side carries a trimmed CalendarPeriod end.
+            Without it, the containment check "trimmedEnd >= MaxValue" silently returns null,
+            causing all binary operators to return Empty and the payrun to fail with Missing results.
+            </summary>
         </member>
         <member name="M:PayrollEngine.Client.Scripting.CasePayrollValue.op_Addition(PayrollEngine.Client.Scripting.CasePayrollValue,PayrollEngine.Client.Scripting.CasePayrollValue)">
             <summary>Addition of two case values</summary>

Directory.Build.props

@@ -2,7 +2,7 @@
 
 	<PropertyGroup>
 		<TargetFramework>net10.0</TargetFramework>
-		<Version>0.10.0-beta.1</Version>
+		<Version>0.10.0-beta.dev</Version>
 		<FileVersion>0.9.0</FileVersion>
 		<InformationalVersion></InformationalVersion>
 		<Authors>Jani Giannoudis</Authors>