@oneuptime/common 11.3.26 → 11.3.28

package/Tests/Types/OnCallDutyPolicy/LayerUtilMonthYearAudit.test.ts

@@ -0,0 +1,255 @@
+import LayerUtil, { LayerProps } from "../../../Types/OnCallDutyPolicy/Layer";
+import RestrictionTimes from "../../../Types/OnCallDutyPolicy/RestrictionTimes";
+import Recurring from "../../../Types/Events/Recurring";
+import EventInterval from "../../../Types/Events/EventInterval";
+import PositiveNumber from "../../../Types/PositiveNumber";
+import OneUptimeDate from "../../../Types/Date";
+import User from "../../../Models/DatabaseModels/User";
+import CalendarEvent from "../../../Types/Calendar/CalendarEvent";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * Audit H1: moveHandsOffTimeAfterCurrentEventStartTime used a single MULTIPLIED
+ * calendar add from the anchor (addRotationUnits(anchor, k*interval)) to place a
+ * rotation boundary. For Month/Year, moment end-of-month-clamps a multiplied add
+ * differently than stepping one period at a time — e.g. Jan-31 + 11 months
+ * multiplied = Dec-31, but iterating eleven +1-month steps = Dec-28. The
+ * current-user counter (countElapsedRotationPeriods) already ITERATES, so the
+ * emitted handoff boundary landed off the grid the current user was resolved on:
+ * the schedule paged the wrong user and fired the handoff nearly a month early
+ * for Month/Year rotations anchored on day 29-31 (or Feb-29 for Year).
+ *
+ * The invariant these tests lock in: the current user + handoff resolved from a
+ * window that opens at "now" must match a full expansion from the layer's anchor
+ * (both walk the SAME iterated grid), and Month/Year boundaries must stay on the
+ * clamped iterated grid (never re-inflate to day 30/31 after a short month).
+ */
+
+function user(id: string): User {
+  return {
+    id: {
+      toString: (): string => {
+        return id;
+      },
+    } as any,
+  } as User;
+}
+
+function rotation(type: EventInterval, count: number): Recurring {
+  const r: Recurring = new Recurring();
+  r.intervalType = type;
+  r.intervalCount = new PositiveNumber(count);
+  return r;
+}
+
+function expandFrom(
+  layer: LayerProps,
+  windowStart: Date,
+  windowEnd: Date,
+): Array<CalendarEvent> {
+  return new LayerUtil().getEvents({
+    ...layer,
+    calendarStartDate: windowStart,
+    calendarEndDate: windowEnd,
+  });
+}
+
+// The event that covers `at` in a full expansion from the layer anchor.
+function coveringEvent(
+  events: Array<CalendarEvent>,
+  at: Date,
+): CalendarEvent | null {
+  for (const event of events) {
+    if (
+      OneUptimeDate.isOnOrBefore(event.start, at) &&
+      OneUptimeDate.isOnOrAfter(event.end, at)
+    ) {
+      return event;
+    }
+  }
+  return null;
+}
+
+describe("LayerUtil audit H1: Month/Year rotation boundary iterated grid", () => {
+  test("monthly rotation anchored Jan-31: current user + handoff from 'now' matches full expansion from anchor", () => {
+    const anchor: Date = new Date(Date.UTC(2025, 0, 31, 0, 0, 0));
+    const now: Date = new Date(Date.UTC(2025, 11, 29, 12, 0, 0));
+    const layer: LayerProps = {
+      users: [user("A"), user("B")],
+      startDateTimeOfLayer: anchor,
+      handOffTime: anchor,
+      restrictionTimes: RestrictionTimes.getDefault(),
+      rotation: rotation(EventInterval.Month, 1),
+      timezone: "America/New_York",
+    };
+
+    const fromNow: Array<CalendarEvent> = expandFrom(
+      layer,
+      now,
+      new Date(Date.UTC(2026, 3, 5, 0, 0, 0)),
+    );
+    const fromAnchor: Array<CalendarEvent> = expandFrom(
+      layer,
+      anchor,
+      new Date(Date.UTC(2026, 3, 5, 0, 0, 0)),
+    );
+
+    const current: CalendarEvent | undefined = fromNow[0];
+    const covering: CalendarEvent | null = coveringEvent(fromAnchor, now);
+
+    expect(current).toBeTruthy();
+    expect(covering).toBeTruthy();
+
+    // Same user on call for "now" whether resolved from now or from the anchor.
+    expect(current!.title).toBe(covering!.title);
+
+    // Same handoff boundary (the crux of the bug — these disagreed before H1).
+    expect(new Date(current!.end).toISOString()).toBe(
+      new Date(covering!.end).toISOString(),
+    );
+
+    // Regression guard: the handoff is in Jan 2026, NOT the buggy Dec-31 2025.
+    const end: Date = new Date(current!.end);
+    expect(end.getUTCFullYear()).toBe(2026);
+    expect(end.getUTCMonth()).toBe(0); // January
+  });
+
+  test("monthly rotation anchored Jan-31: no emitted boundary re-inflates past day 29 after a short month", () => {
+    const anchor: Date = new Date(Date.UTC(2025, 0, 31, 0, 0, 0));
+    const layer: LayerProps = {
+      users: [user("A"), user("B")],
+      startDateTimeOfLayer: anchor,
+      handOffTime: anchor,
+      restrictionTimes: RestrictionTimes.getDefault(),
+      rotation: rotation(EventInterval.Month, 1),
+      timezone: "UTC",
+    };
+
+    const events: Array<CalendarEvent> = expandFrom(
+      layer,
+      anchor,
+      new Date(Date.UTC(2026, 11, 1, 0, 0, 0)),
+    );
+
+    /*
+     * After Jan-31 the iterated grid drops to Feb-28 and stays on day <= 28
+     * (28 in UTC). The buggy multiplied form produced Mar-31, Apr-30, ... —
+     * boundary days of 30/31. Assert every internal handoff boundary is on day
+     * <= 29 (allowing month-length clamping wiggle), which the multiplied form
+     * violated. The final event ends at the clamped calendarEnd, so skip it.
+     */
+    for (let i: number = 0; i < events.length - 1; i++) {
+      const end: Date = new Date(events[i]!.end);
+      expect(end.getUTCDate()).toBeLessThanOrEqual(29);
+    }
+  });
+
+  test("monthly rotation with intervalCount=3 stays consistent (current == full-expansion covering)", () => {
+    const anchor: Date = new Date(Date.UTC(2025, 0, 31, 0, 0, 0));
+    const now: Date = new Date(Date.UTC(2026, 0, 15, 6, 0, 0));
+    const layer: LayerProps = {
+      users: [user("A"), user("B"), user("C")],
+      startDateTimeOfLayer: anchor,
+      handOffTime: anchor,
+      restrictionTimes: RestrictionTimes.getDefault(),
+      rotation: rotation(EventInterval.Month, 3),
+      timezone: "America/New_York",
+    };
+
+    const fromNow: Array<CalendarEvent> = expandFrom(
+      layer,
+      now,
+      new Date(Date.UTC(2026, 8, 1, 0, 0, 0)),
+    );
+    const fromAnchor: Array<CalendarEvent> = expandFrom(
+      layer,
+      anchor,
+      new Date(Date.UTC(2026, 8, 1, 0, 0, 0)),
+    );
+
+    const current: CalendarEvent | undefined = fromNow[0];
+    const covering: CalendarEvent | null = coveringEvent(fromAnchor, now);
+
+    expect(current).toBeTruthy();
+    expect(covering).toBeTruthy();
+    expect(current!.title).toBe(covering!.title);
+    expect(new Date(current!.end).toISOString()).toBe(
+      new Date(covering!.end).toISOString(),
+    );
+  });
+
+  test("yearly rotation anchored Feb-29 (leap): boundary clamps to Feb-28 and stays consistent", () => {
+    const anchor: Date = new Date(Date.UTC(2024, 1, 29, 0, 0, 0));
+    const now: Date = new Date(Date.UTC(2027, 5, 1, 0, 0, 0));
+    const layer: LayerProps = {
+      users: [user("A"), user("B")],
+      startDateTimeOfLayer: anchor,
+      handOffTime: anchor,
+      restrictionTimes: RestrictionTimes.getDefault(),
+      rotation: rotation(EventInterval.Year, 1),
+      timezone: "UTC",
+    };
+
+    const fromNow: Array<CalendarEvent> = expandFrom(
+      layer,
+      now,
+      new Date(Date.UTC(2031, 0, 1, 0, 0, 0)),
+    );
+    const fromAnchor: Array<CalendarEvent> = expandFrom(
+      layer,
+      anchor,
+      new Date(Date.UTC(2031, 0, 1, 0, 0, 0)),
+    );
+
+    const current: CalendarEvent | undefined = fromNow[0];
+    const covering: CalendarEvent | null = coveringEvent(fromAnchor, now);
+
+    expect(current).toBeTruthy();
+    expect(covering).toBeTruthy();
+    expect(current!.title).toBe(covering!.title);
+    expect(new Date(current!.end).toISOString()).toBe(
+      new Date(covering!.end).toISOString(),
+    );
+
+    /*
+     * The first post-anchor yearly boundary must be Feb-28 (non-leap), not
+     * Feb-29 re-inflated by a multiplied add.
+     */
+    const firstBoundary: CalendarEvent | undefined = fromAnchor[0];
+    expect(firstBoundary).toBeTruthy();
+    const end: Date = new Date(firstBoundary!.end);
+    expect(end.getUTCMonth()).toBe(1); // February
+    expect(end.getUTCDate()).toBe(28);
+  });
+
+  test("Day and Week rotations are unaffected (no calendar clamping) — sanity", () => {
+    const anchor: Date = new Date(Date.UTC(2025, 0, 31, 0, 0, 0));
+    const now: Date = new Date(Date.UTC(2025, 5, 15, 9, 0, 0));
+    const layer: LayerProps = {
+      users: [user("A"), user("B")],
+      startDateTimeOfLayer: anchor,
+      handOffTime: anchor,
+      restrictionTimes: RestrictionTimes.getDefault(),
+      rotation: rotation(EventInterval.Day, 1),
+      timezone: "UTC",
+    };
+
+    const fromNow: Array<CalendarEvent> = expandFrom(
+      layer,
+      now,
+      new Date(Date.UTC(2025, 5, 20, 0, 0, 0)),
+    );
+    const fromAnchor: Array<CalendarEvent> = expandFrom(
+      layer,
+      anchor,
+      new Date(Date.UTC(2025, 5, 20, 0, 0, 0)),
+    );
+
+    const current: CalendarEvent | undefined = fromNow[0];
+    const covering: CalendarEvent | null = coveringEvent(fromAnchor, now);
+    expect(current!.title).toBe(covering!.title);
+    expect(new Date(current!.end).toISOString()).toBe(
+      new Date(covering!.end).toISOString(),
+    );
+  });
+});

package/Tests/Types/OnCallDutyPolicy/LayerUtilMultiLayerAudit.test.ts

@@ -0,0 +1,388 @@
+import LayerUtil, { LayerProps } from "../../../Types/OnCallDutyPolicy/Layer";
+import CalendarEvent from "../../../Types/Calendar/CalendarEvent";
+import RestrictionTimes, {
+  RestrictionType,
+  WeeklyResctriction,
+} from "../../../Types/OnCallDutyPolicy/RestrictionTimes";
+import Recurring from "../../../Types/Events/Recurring";
+import OneUptimeDate from "../../../Types/Date";
+import User from "../../../Models/DatabaseModels/User";
+import EventInterval from "../../../Types/Events/EventInterval";
+import DayOfWeek from "../../../Types/Day/DayOfWeek";
+
+function user(id: string): User {
+  return {
+    id: {
+      toString: () => {
+        return id;
+      },
+    } as any,
+  } as User;
+}
+
+function rotation(t: EventInterval, c: number): Recurring {
+  return Recurring.fromJSON({
+    _type: "Recurring",
+    value: {
+      intervalType: t,
+      intervalCount: { _type: "PositiveNumber", value: c },
+    },
+  } as any);
+}
+
+function noRestriction(): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.None;
+  r.dayRestrictionTimes = null;
+  return r;
+}
+
+function dailyRestriction(
+  startHour: number,
+  endHour: number,
+): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.Daily;
+  r.dayRestrictionTimes = {
+    startTime: OneUptimeDate.getDateWithCustomTime({
+      hours: startHour,
+      minutes: 0,
+      seconds: 0,
+    }),
+    endTime: OneUptimeDate.getDateWithCustomTime({
+      hours: endHour,
+      minutes: 0,
+      seconds: 0,
+    }),
+  };
+  return r;
+}
+
+function weeklyRestriction(
+  windows: Array<{
+    startDay: DayOfWeek;
+    endDay: DayOfWeek;
+    startHour: number;
+    endHour: number;
+  }>,
+): RestrictionTimes {
+  const r: RestrictionTimes = new RestrictionTimes();
+  r.restictionType = RestrictionType.Weekly;
+  r.dayRestrictionTimes = null;
+  r.weeklyRestrictionTimes = windows.map(
+    (w: {
+      startDay: DayOfWeek;
+      endDay: DayOfWeek;
+      startHour: number;
+      endHour: number;
+    }): WeeklyResctriction => {
+      return {
+        startDay: w.startDay,
+        endDay: w.endDay,
+        startTime: OneUptimeDate.getDateWithCustomTime({
+          hours: w.startHour,
+          minutes: 0,
+          seconds: 0,
+        }),
+        endTime: OneUptimeDate.getDateWithCustomTime({
+          hours: w.endHour,
+          minutes: 0,
+          seconds: 0,
+        }),
+      };
+    },
+  );
+  return r;
+}
+
+// Which user covers instant t in a single event list? half-open [start, end).
+function coveringUser(events: Array<CalendarEvent>, t: Date): string | null {
+  for (const e of events) {
+    if (e.start.getTime() <= t.getTime() && e.end.getTime() > t.getTime()) {
+      return e.title;
+    }
+  }
+  return null;
+}
+
+/*
+ * Oracle: expected on-call user at instant t across layers, resolved by priority
+ * (lowest layer index that covers t wins). Uses each layer's own getEvents.
+ */
+function oracleUser(
+  perLayerEvents: Array<Array<CalendarEvent>>,
+  t: Date,
+): string | null {
+  for (const layerEvents of perLayerEvents) {
+    const u: string | null = coveringUser(layerEvents, t);
+    if (u !== null) {
+      return u;
+    }
+  }
+  return null;
+}
+
+// Returns overlapping pairs (real double-coverage, more than the 1s seam).
+function overlappingPairs(
+  events: Array<CalendarEvent>,
+): Array<[CalendarEvent, CalendarEvent]> {
+  const pairs: Array<[CalendarEvent, CalendarEvent]> = [];
+  for (let i: number = 0; i < events.length; i++) {
+    for (let j: number = i + 1; j < events.length; j++) {
+      const a: CalendarEvent = events[i]!;
+      const b: CalendarEvent = events[j]!;
+      // overlap in seconds of [a.start,a.end) ∩ [b.start,b.end)
+      const start: number = Math.max(a.start.getTime(), b.start.getTime());
+      const end: number = Math.min(a.end.getTime(), b.end.getTime());
+      if (end - start > 0) {
+        pairs.push([a, b]);
+      }
+    }
+  }
+  return pairs;
+}
+
+describe("Multi-layer priority merge audit (lens: getMultiLayerEvents / removeOverlappingEvents)", () => {
+  const util: LayerUtil = new LayerUtil();
+
+  /*
+   * Runs the merge and compares against the per-layer priority oracle at many
+   * instants. Also asserts no real overlap (no double paging).
+   */
+  function checkMerge(
+    layers: Array<LayerProps>,
+    calStart: Date,
+    calEnd: Date,
+    sampleStepMinutes: number = 30,
+  ): { mismatches: Array<string>; overlaps: number } {
+    const merged: Array<CalendarEvent> = util.getMultiLayerEvents({
+      layers: layers,
+      calendarStartDate: calStart,
+      calendarEndDate: calEnd,
+    });
+
+    const perLayerEvents: Array<Array<CalendarEvent>> = layers.map(
+      (layer: LayerProps): Array<CalendarEvent> => {
+        return util.getEvents({
+          ...layer,
+          calendarStartDate: calStart,
+          calendarEndDate: calEnd,
+        });
+      },
+    );
+
+    const mismatches: Array<string> = [];
+
+    // Sample instants offset by 17s from clean boundaries to avoid 1s seams.
+    for (
+      let ms: number = calStart.getTime() + 17000;
+      ms < calEnd.getTime();
+      ms += sampleStepMinutes * 60 * 1000
+    ) {
+      const t: Date = new Date(ms);
+      const expected: string | null = oracleUser(perLayerEvents, t);
+      const actual: string | null = coveringUser(merged, t);
+      if (expected !== actual) {
+        mismatches.push(
+          `${OneUptimeDate.toString(t)} expected=${expected} actual=${actual}`,
+        );
+      }
+    }
+
+    const overlaps: Array<[CalendarEvent, CalendarEvent]> =
+      overlappingPairs(merged);
+
+    return { mismatches: mismatches, overlaps: overlaps.length };
+  }
+
+  test("Scenario A: three 24/7 layers, different rotations -> highest priority always wins, no gaps/overlaps", () => {
+    const calStart: Date = new Date(2026, 0, 5, 0, 0, 0); // Mon Jan 5 2026
+    const calEnd: Date = new Date(2026, 0, 26, 0, 0, 0); // 3 weeks
+
+    const layers: Array<LayerProps> = [
+      {
+        users: [user("A1"), user("A2")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+      {
+        users: [user("B1"), user("B2"), user("B3")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Day, 2),
+      },
+      {
+        users: [user("C1")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+    ];
+
+    const { mismatches, overlaps } = checkMerge(layers, calStart, calEnd);
+    // Layer 0 is 24/7, so it always wins; every instant should be A1/A2.
+    expect(mismatches).toEqual([]);
+    expect(overlaps).toBe(0);
+  });
+
+  test("Scenario B: business-hours primary (Daily 09-17) over 24/7 fallback", () => {
+    const calStart: Date = new Date(2026, 0, 5, 0, 0, 0);
+    const calEnd: Date = new Date(2026, 0, 19, 0, 0, 0); // 2 weeks
+
+    const layers: Array<LayerProps> = [
+      {
+        users: [user("P1"), user("P2")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: dailyRestriction(9, 17),
+        handOffTime: new Date(2026, 0, 5, 12, 0, 0),
+        rotation: rotation(EventInterval.Day, 1),
+      },
+      {
+        users: [user("F1"), user("F2")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+    ];
+
+    const { mismatches, overlaps } = checkMerge(layers, calStart, calEnd);
+    expect(mismatches).toEqual([]);
+    expect(overlaps).toBe(0);
+  });
+
+  test("Scenario C: TWO restricted primaries over a 24/7 fallback (3 layers)", () => {
+    const calStart: Date = new Date(2026, 0, 5, 0, 0, 0);
+    const calEnd: Date = new Date(2026, 0, 19, 0, 0, 0);
+
+    const layers: Array<LayerProps> = [
+      // Highest: mornings 06-10
+      {
+        users: [user("M1"), user("M2")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: dailyRestriction(6, 10),
+        handOffTime: new Date(2026, 0, 5, 8, 0, 0),
+        rotation: rotation(EventInterval.Day, 1),
+      },
+      // Middle: afternoons 14-18
+      {
+        users: [user("N1"), user("N2")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: dailyRestriction(14, 18),
+        handOffTime: new Date(2026, 0, 5, 16, 0, 0),
+        rotation: rotation(EventInterval.Day, 1),
+      },
+      // Fallback: 24/7
+      {
+        users: [user("Z1")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+    ];
+
+    const { mismatches, overlaps } = checkMerge(layers, calStart, calEnd);
+    expect(mismatches).toEqual([]);
+    expect(overlaps).toBe(0);
+  });
+
+  test("Scenario D: overlapping restricted primaries (both high priority) over fallback", () => {
+    const calStart: Date = new Date(2026, 0, 5, 0, 0, 0);
+    const calEnd: Date = new Date(2026, 0, 12, 0, 0, 0);
+
+    const layers: Array<LayerProps> = [
+      // Highest: 08-14
+      {
+        users: [user("H1")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: dailyRestriction(8, 14),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+      // Second: 10-18 (OVERLAPS the first at 10-14)
+      {
+        users: [user("K1")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: dailyRestriction(10, 18),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+      // Fallback 24/7
+      {
+        users: [user("Z1")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+    ];
+
+    const { mismatches, overlaps } = checkMerge(layers, calStart, calEnd);
+    expect(mismatches).toEqual([]);
+    expect(overlaps).toBe(0);
+  });
+
+  test("Scenario E: weekly-restricted primary (weekdays only) over 24/7 fallback", () => {
+    const calStart: Date = new Date(2026, 0, 5, 0, 0, 0); // Mon
+    const calEnd: Date = new Date(2026, 0, 26, 0, 0, 0);
+
+    const layers: Array<LayerProps> = [
+      {
+        users: [user("W1"), user("W2")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: weeklyRestriction([
+          {
+            startDay: DayOfWeek.Monday,
+            endDay: DayOfWeek.Friday,
+            startHour: 9,
+            endHour: 17,
+          },
+        ]),
+        handOffTime: new Date(2026, 0, 5, 12, 0, 0),
+        rotation: rotation(EventInterval.Day, 1),
+      },
+      {
+        users: [user("F1")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+    ];
+
+    const { mismatches, overlaps } = checkMerge(layers, calStart, calEnd);
+    expect(mismatches).toEqual([]);
+    expect(overlaps).toBe(0);
+  });
+
+  test("Scenario F: fast rotation primary (hourly) restricted over fallback", () => {
+    const calStart: Date = new Date(2026, 0, 5, 0, 0, 0);
+    const calEnd: Date = new Date(2026, 0, 8, 0, 0, 0);
+
+    const layers: Array<LayerProps> = [
+      {
+        users: [user("A"), user("B"), user("C")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: dailyRestriction(9, 17),
+        handOffTime: new Date(2026, 0, 5, 9, 0, 0),
+        rotation: rotation(EventInterval.Hour, 1),
+      },
+      {
+        users: [user("Z")],
+        startDateTimeOfLayer: calStart,
+        restrictionTimes: noRestriction(),
+        handOffTime: calStart,
+        rotation: rotation(EventInterval.Week, 1),
+      },
+    ];
+
+    const { mismatches, overlaps } = checkMerge(layers, calStart, calEnd, 7);
+    expect(mismatches).toEqual([]);
+    expect(overlaps).toBe(0);
+  });
+});