ClawdDotNet/tests/ClawdDotNet.Core.Tests/Tasks/TaskScheduleTests.cs

using ClawdDotNet.Core.Tasks;
using Shouldly;

namespace ClawdDotNet.Core.Tests.Tasks;

/// <summary>
/// The schedule calculation — answer to B6 (no delays, only "what is due now")
/// and B7 (every occurrence is explicitly interpreted in its time zone). A pure function,
/// therefore without DB and without a fake clock: "now" is passed in directly.
/// </summary>
public sealed class TaskScheduleTests
{
    private static DateTime Utc(int y, int mo, int d, int h, int mi)
        => new(y, mo, d, h, mi, 0, DateTimeKind.Utc);

    // ─── #597: invalid cron expression ───

    [Fact]
    public void Invalid_cron_expression_is_named_instead_of_hidden()
    {
        var task = new TaskItem
        {
            Id = "t-1", CreatedAt = Utc(2026, 9, 14, 6, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 7-22/x * * *", TimeZone = "Europe/Berlin" }
        };

        TaskSchedule.DueOccurrence(task, Utc(2026, 9, 14, 11, 0)).ShouldBeNull();
        TaskSchedule.InvalidCron(task).ShouldNotBeNull().ShouldContain("'x' ist keine Zahl");
    }

    [Fact]
    public void News_digest_from_test_operation_is_due_at_13_o_clock()
    {
        var task = new TaskItem
        {
            Id = "t-7e0bbe", CreatedAt = Utc(2026, 9, 14, 10, 30),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 7-22/3 * * *", TimeZone = "Europe/Berlin" }
        };

        TaskSchedule.InvalidCron(task).ShouldBeNull();
        // 13:00 Berlin (CEST) = 11:00 UTC
        TaskSchedule.DueOccurrence(task, Utc(2026, 9, 14, 11, 0)).ShouldBe("2026-09-14T11:00:00.0000000Z");
    }

    [Fact]
    public void Other_schedule_kinds_have_no_cron_error()
        => TaskSchedule.InvalidCron(new TaskItem
        {
            Id = "t-1", When = new TaskWhen { Kind = TaskWhenKind.Every, Value = "kaputt" }
        }).ShouldBeNull();

    // ─── One-time, without a schedule ───

    [Fact]
    public void Without_schedule_the_task_is_due_until_it_ran()
    {
        var task = new TaskItem { Id = "t-1", CreatedAt = Utc(2026, 7, 31, 6, 0) };

        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 7, 0)).ShouldNotBeNull();
        TaskSchedule.DueOccurrence(task with { LastOccurrence = "x" }, Utc(2026, 7, 31, 7, 0)).ShouldBeNull();
    }

    // ─── at: one-time point in time ───

    [Fact]
    public void An_at_schedule_is_only_due_from_its_time()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            When = new TaskWhen { Kind = TaskWhenKind.At, Value = "2026-07-31T09:00:00", TimeZone = "Europe/Berlin" }
        };

        // 09:00 Berlin (summer time) = 07:00 UTC
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 6, 59)).ShouldBeNull();
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 7, 0)).ShouldNotBeNull();
    }

    [Fact]
    public void An_at_schedule_fires_exactly_once()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            LastOccurrence = "2026-07-31T07:00:00.0000000Z",
            When = new TaskWhen { Kind = TaskWhenKind.At, Value = "2026-07-31T09:00:00", TimeZone = "Europe/Berlin" }
        };

        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 12, 0)).ShouldBeNull();
    }

    [Fact]
    public void An_at_schedule_with_Z_is_interpreted_as_UTC()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            When = new TaskWhen { Kind = TaskWhenKind.At, Value = "2026-07-31T09:00:00Z", TimeZone = "Europe/Berlin" }
        };

        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 8, 59)).ShouldBeNull();
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 9, 0)).ShouldNotBeNull();
    }

    // ─── every: interval ───

    [Fact]
    public void An_interval_only_becomes_due_after_it_elapses()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 7, 31, 7, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Every, Value = "30m", TimeZone = "UTC" }
        };

        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 7, 20)).ShouldBeNull();
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 7, 30)).ShouldNotBeNull();
    }

    [Fact]
    public void After_the_marker_the_interval_counts_anew()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            LastOccurrence = "2026-07-31T07:30:00.0000000Z",
            When = new TaskWhen { Kind = TaskWhenKind.Every, Value = "30m", TimeZone = "UTC" }
        };

        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 7, 55)).ShouldBeNull();
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 8, 0)).ShouldNotBeNull();
    }

    // ─── cron: with time zone (the core of B7) ───

    [Fact]
    public void A_cron_schedule_is_interpreted_in_its_time_zone_summer()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 7, 31, 0, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = "Europe/Berlin" }
        };

        // 09:00 Berlin in summer (CEST, UTC+2) = 07:00 UTC
        var occ = TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 7, 5));
        occ.ShouldBe("2026-07-31T07:00:00.0000000Z");
    }

    [Fact]
    public void The_same_cron_lands_on_a_different_UTC_hour_in_winter()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 1, 15, 0, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = "Europe/Berlin" }
        };

        // 09:00 Berlin in winter (CET, UTC+1) = 08:00 UTC — exactly what B7 demands.
        var occ = TaskSchedule.DueOccurrence(task, Utc(2026, 1, 15, 8, 5));
        occ.ShouldBe("2026-01-15T08:00:00.0000000Z");
    }

    [Fact]
    public void Before_the_planned_time_the_cron_is_not_due()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 7, 31, 5, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = "Europe/Berlin" }
        };

        // 06:00 UTC = 08:00 Berlin, before the 09:00 mark
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 6, 0)).ShouldBeNull();
    }

    [Fact]
    public void A_fresh_cron_task_does_not_catch_up_an_occurrence_from_before_its_creation()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 7, 31, 8, 0), // after today's 09:00 Berlin mark (07:00 UTC)
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = "Europe/Berlin" }
        };

        // Now 10:00 UTC — today's 09:00 mark was before creation, so do not catch up.
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 10, 0)).ShouldBeNull();
    }

    [Fact]
    public void The_same_cron_occurrence_does_not_fire_twice()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            LastOccurrence = "2026-07-31T07:00:00.0000000Z",
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = "Europe/Berlin" }
        };

        // Later on the same day: the 09:00 occurrence is already ticked off.
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 10, 0)).ShouldBeNull();

        // The next day is due again.
        TaskSchedule.DueOccurrence(task, Utc(2026, 8, 1, 7, 5)).ShouldBe("2026-08-01T07:00:00.0000000Z");
    }

    [Fact]
    public void A_broken_cron_expression_does_not_topple_the_scanner()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "kein cron", TimeZone = "UTC" }
        };

        Should.NotThrow(() => TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 9, 0)))
            .ShouldBeNull();
    }

    /// <summary>
    /// Formerly an unknown zone silently fell back to UTC. That is the worse
    /// error: a task for 09:00 local time ran at 07:00 in summer without anything
    /// being noticed anywhere. Now it does not fire at all — and the scanner reports once why.
    /// </summary>
    [Fact]
    public void An_unknown_time_zone_does_not_make_the_schedule_due()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 7, 31, 0, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = "Phantasie/Ort" }
        };

        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 9, 5)).ShouldBeNull();
        TaskSchedule.UnresolvableTimeZone(task).ShouldBe("Phantasie/Ort");
    }

    /// <summary>
    /// The core of the port: the same time zone, two spellings. A task file
    /// created under Windows must yield the same fire time under Linux —
    /// and vice versa.
    /// </summary>
    [Theory]
    [InlineData("Europe/Berlin")]
    [InlineData("W. Europe Standard Time")]
    public void Both_spellings_of_the_same_zone_give_the_same_fire_time(string tz)
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 7, 31, 0, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = tz }
        };

        TaskSchedule.UnresolvableTimeZone(task).ShouldBeNull();

        // 09:00 local time in summer (CEST, UTC+2) = 07:00 UTC.
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 9, 5))
            .ShouldBe("2026-07-31T07:00:00.0000000Z");
    }

    [Fact]
    public void No_time_zone_still_means_UTC()
    {
        var task = new TaskItem
        {
            Id = "t-1",
            CreatedAt = Utc(2026, 7, 31, 0, 0),
            When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 9 * * *", TimeZone = "" }
        };

        TaskSchedule.UnresolvableTimeZone(task).ShouldBeNull();
        TaskSchedule.DueOccurrence(task, Utc(2026, 7, 31, 9, 5))
            .ShouldBe("2026-07-31T09:00:00.0000000Z");
    }

    // ═══════════════════════════════════════════════════════════
    //  Daylight saving changes — R4 and R5 of the test strategy
    //
    //  Europe/Berlin 2026: on 29 March the clock jumps at 02:00 to 03:00, on
    //  25 October at 03:00 back to 02:00. A daily occurrence at 02:00 thus hits
    //  once a year a time that does not exist, and once one that exists
    //  twice.
    // ═══════════════════════════════════════════════════════════

    private static TaskItem DailyAtTwo(DateTime created) => new()
    {
        Id = "t-dst",
        CreatedAt = created,
        When = new TaskWhen { Kind = TaskWhenKind.Cron, Value = "0 2 * * *", TimeZone = "Europe/Berlin" }
    };

    /// <summary>R5 — the case #235 is about.</summary>
    [Fact]
    public void DST_change_in_March_is_not_skipped()
    {
        var task = DailyAtTwo(Utc(2026, 3, 28, 0, 0));

        // "02:00" does not exist on 29 March. The occurrence still happens, namely
        // at the first point in time after it: 03:00 CEST = 01:00 UTC.
        // Previously null came here — the task was dropped on that day without replacement.
        TaskSchedule.DueOccurrence(task, Utc(2026, 3, 29, 2, 0))
            .ShouldBe("2026-03-29T01:00:00.0000000Z");
    }

    [Fact]
    public void The_shifted_occurrence_still_fires_only_once()
    {
        var task = DailyAtTwo(Utc(2026, 3, 28, 0, 0));

        var firstDue = TaskSchedule.DueOccurrence(task, Utc(2026, 3, 29, 2, 0));
        firstDue.ShouldNotBeNull();

        TaskSchedule.DueOccurrence(task with { LastOccurrence = firstDue }, Utc(2026, 3, 29, 2, 30))
            .ShouldBeNull();
    }

    /// <summary>R4 — the other direction.</summary>
    [Fact]
    public void DST_change_in_October_fires_exactly_once()
    {
        var task = DailyAtTwo(Utc(2026, 10, 24, 0, 0));

        // 02:00 occurs twice on 25 October: in summer time (00:00 UTC) and in
        // standard time (01:00 UTC). Both passes result in the same occurrence key —
        // the marker catches the second.
        var firstPass = TaskSchedule.DueOccurrence(task, Utc(2026, 10, 25, 0, 30));
        firstPass.ShouldNotBeNull();

        var secondPass = TaskSchedule.DueOccurrence(
            task with { LastOccurrence = firstPass }, Utc(2026, 10, 25, 1, 30));
        secondPass.ShouldBeNull();
    }

    [Fact]
    public void On_ordinary_days_it_stays_at_two_o_clock_local_time()
    {
        // The counter-check: the shift may only apply in the gap.
        var task = DailyAtTwo(Utc(2026, 3, 21, 0, 0));

        // 02:00 CET = 01:00 UTC.
        TaskSchedule.DueOccurrence(task, Utc(2026, 3, 22, 2, 0))
            .ShouldBe("2026-03-22T01:00:00.0000000Z");
    }

    [Fact]
    public void A_one_off_schedule_in_the_gap_is_not_skipped_either()
    {
        // The same handling on the at path — the same rule and the same gap applied there.
        var task = new TaskItem
        {
            Id = "t-1",
            When = new TaskWhen
            {
                Kind = TaskWhenKind.At,
                Value = "2026-03-29T02:30:00",
                TimeZone = "Europe/Berlin"
            }
        };

        // 02:30 does not exist; it becomes 03:00 CEST = 01:00 UTC.
        TaskSchedule.DueOccurrence(task, Utc(2026, 3, 29, 0, 59)).ShouldBeNull();
        TaskSchedule.DueOccurrence(task, Utc(2026, 3, 29, 1, 0))
            .ShouldBe("2026-03-29T01:00:00.0000000Z");
    }
}