/** * Tests for quarter arithmetic and the projected event shape. * * The calendar has no storage of its own, so there is nothing to inspect when * a bucket is wrong — a deal simply appears under the wrong heading and the * quarterly number is quietly off. The cases below therefore pin the two * decisions that a plausible-but-wrong implementation gets backwards: which * calendar year names a fiscal year, and whether the upper bound is inclusive. */ import { strict as assert } from 'node:assert'; import { describe, it } from 'node:test'; import { CALENDAR_EVENT_KINDS, calendarEventId, completableSpanState, eventState, isCalendarEventKind, isValidTimeZone, parseQuarter, quarterBounds, quarterBoundsFor, quarterOf, spanState, } from '../src/calendar'; describe('quarterOf', () => { it('buckets calendar quarters', () => { assert.equal(quarterOf(new Date('2026-01-01T00:00:00.000Z')), '2026-Q1'); assert.equal(quarterOf(new Date('2026-08-13T12:00:00.000Z')), '2026-Q3'); assert.equal(quarterOf(new Date('2026-12-31T23:59:59.999Z')), '2026-Q4'); }); it('names a fiscal year for the calendar year it ENDS in', () => { // The decision. A fiscal year starting April 2026 runs to March 2027 and // is FY2027 — the convention used by the companies whose paper PIG holds. // Naming it FY2026 instead is the plausible-but-wrong version: it puts // every April-to-December deal a year early, and the error is invisible // because the quarter number is right. assert.equal(quarterOf(new Date('2026-04-01T00:00:00.000Z'), 3), '2027-Q1'); assert.equal(quarterOf(new Date('2026-08-13T00:00:00.000Z'), 3), '2027-Q2'); assert.equal(quarterOf(new Date('2027-03-31T23:00:00.000Z'), 3), '2027-Q4'); // The next fiscal year begins the following day, and the label advances. assert.equal(quarterOf(new Date('2027-04-01T00:00:00.000Z'), 3), '2028-Q1'); }); it('handles the year boundary under an October fiscal start', () => { // A US-federal-style year: October 2026 is already FY2027 Q1, while // September 2026 is still FY2026 Q4. A naive implementation that derives // the label from the calendar year alone puts these in the same year. assert.equal(quarterOf(new Date('2026-09-30T23:59:59.999Z'), 9), '2026-Q4'); assert.equal(quarterOf(new Date('2026-10-01T00:00:00.000Z'), 9), '2027-Q1'); assert.equal(quarterOf(new Date('2026-12-31T23:59:59.999Z'), 9), '2027-Q1'); assert.equal(quarterOf(new Date('2027-01-01T00:00:00.000Z'), 9), '2027-Q2'); }); it('buckets by the reader time zone, not by UTC', () => { // Every temporal column in PIG is `timestamp with time zone`, so a // quarter boundary is a local-midnight question. This instant is already // Q1 in London and still Q4 in New York; bucketing everything in UTC // silently reports one of the two readers a wrong quarterly total. const newYearInLondon = new Date('2027-01-01T00:30:00.000Z'); assert.equal(quarterOf(newYearInLondon, 0, 'Europe/London'), '2027-Q1'); assert.equal(quarterOf(newYearInLondon, 0, 'America/New_York'), '2026-Q4'); }); it('falls back to UTC rather than throwing on an unusable zone', () => { // `users.timezone` is free text and nothing validates it on write. assert.equal(quarterOf(new Date('2026-08-13T12:00:00.000Z'), 0, 'Mars/Olympus'), '2026-Q3'); }); it('rejects a fiscal start that is not a month index', () => { assert.throws(() => quarterOf(new Date(), 12), RangeError); assert.throws(() => quarterOf(new Date(), -1), RangeError); }); }); describe('quarterBounds', () => { it('is half-open, so consecutive quarters tile without overlapping', () => { // An inclusive upper bound files a contract expiring at exactly midnight // on 1 October into both Q3 and Q4, and adding the two quarters together // then counts its value twice. const q3 = quarterBounds(2026, 3); const q4 = quarterBounds(2026, 4); assert.equal(q3.from.toISOString(), '2026-07-01T00:00:00.000Z'); assert.equal(q3.to.toISOString(), '2026-10-01T00:00:00.000Z'); assert.equal(q3.to.getTime(), q4.from.getTime()); assert.equal(quarterOf(q3.to), '2026-Q4', 'the upper bound belongs to the NEXT quarter'); }); it('rolls into the following calendar year for a fiscal offset', () => { // FY2027 under an April start began in April 2026, so its Q4 is the first // calendar quarter of 2027. Reading `year` as the starting calendar year // puts this a whole year out. const q1 = quarterBounds(2027, 1, 3); const q4 = quarterBounds(2027, 4, 3); assert.equal(q1.from.toISOString(), '2026-04-01T00:00:00.000Z'); assert.equal(q4.from.toISOString(), '2027-01-01T00:00:00.000Z'); assert.equal(q4.to.toISOString(), '2027-04-01T00:00:00.000Z'); assert.equal(q4.quarter, '2027-Q4'); }); it('round-trips with quarterOf at both ends of every fiscal offset', () => { for (const fiscalStart of [0, 1, 3, 6, 9, 11]) { for (const quarter of [1, 2, 3, 4] as const) { const bounds = quarterBounds(2027, quarter, fiscalStart); assert.equal(quarterOf(bounds.from, fiscalStart), bounds.quarter); assert.equal( quarterOf(new Date(bounds.to.getTime() - 1), fiscalStart), bounds.quarter, `last instant of ${bounds.quarter} at fiscal start ${fiscalStart}`, ); } } }); it('anchors on local midnight, not on UTC midnight', () => { // New York is five hours behind in January, so its Q1 opens at 05:00Z. const q1 = quarterBounds(2026, 1, 0, 'America/New_York'); assert.equal(q1.from.toISOString(), '2026-01-01T05:00:00.000Z'); }); it('survives a quarter that opens across a daylight-saving transition', () => { // Sydney's Q4 opens on the morning clocks go forward; a fixed-offset // implementation lands an hour out and mis-buckets everything on 1 October. const q4 = quarterBounds(2026, 4, 0, 'Australia/Sydney'); assert.equal(quarterOf(q4.from, 0, 'Australia/Sydney'), '2026-Q4'); assert.equal( quarterOf(new Date(q4.from.getTime() - 1), 0, 'Australia/Sydney'), '2026-Q3', ); }); it('rejects a quarter outside 1–4', () => { assert.throws(() => quarterBounds(2026, 0 as 1), RangeError); assert.throws(() => quarterBounds(2026, 5 as 1), RangeError); }); }); describe('quarterBoundsFor and parseQuarter', () => { it('contains the instant it was derived from', () => { const date = new Date('2026-08-13T12:00:00.000Z'); const bounds = quarterBoundsFor(date, 3, 'Europe/London'); assert.equal(bounds.quarter, '2027-Q2'); assert.ok(bounds.from <= date && date < bounds.to); }); it('rejects a malformed label rather than guessing', () => { assert.deepEqual(parseQuarter('2026-Q3'), { year: 2026, quarter: 3 }); assert.equal(parseQuarter('2026-Q5'), null); assert.equal(parseQuarter('26-Q3'), null); assert.equal(parseQuarter('2026Q3'), null); }); }); describe('event state', () => { const now = new Date('2026-08-13T12:00:00.000Z'); const inDays = (days: number) => new Date(now.getTime() + days * 86_400_000); it('reads completion from the column, never from the clock', () => { // A renewal notice whose date has passed is overdue, not finished. assert.equal(eventState({ at: inDays(-3), now }), 'overdue'); assert.equal( eventState({ at: inDays(-3), now, completedAt: inDays(-4) }), 'done', 'only a completion timestamp closes an event', ); }); it('separates due from upcoming on the action horizon', () => { assert.equal(eventState({ at: inDays(3), now }), 'due'); assert.equal(eventState({ at: inDays(30), now }), 'upcoming'); }); it('judges a span by its end, because a running window is not late', () => { assert.equal(spanState({ startsAt: inDays(-10), endsAt: inDays(10), now }), 'due'); assert.equal(spanState({ startsAt: inDays(-30), endsAt: inDays(-1), now }), 'done'); assert.equal(spanState({ startsAt: inDays(60), endsAt: inDays(90), now }), 'upcoming'); }); it('never lets a clock close a span that has a completion column', () => { // The defect this pins: a QBR scheduled last week and never held read // `done` under `spanState`, while the same QBR entered with no end time // read `overdue`. Whether a missed human commitment is flagged then // depends on nothing but whether its author typed an end time. const missed = { startsAt: inDays(-30), endsAt: inDays(-1), now }; assert.equal(completableSpanState(missed), 'overdue'); assert.equal(eventState({ at: missed.startsAt, now }), 'overdue', 'and agrees with a point'); assert.equal(completableSpanState({ ...missed, completedAt: inDays(-2) }), 'done'); assert.equal(spanState(missed), 'done', 'the windowed reading is still right for windows'); }); it('still reads a running or future completable span from its end and start', () => { assert.equal( completableSpanState({ startsAt: inDays(-10), endsAt: inDays(10), now }), 'due', ); assert.equal( completableSpanState({ startsAt: inDays(60), endsAt: inDays(90), now }), 'upcoming', ); assert.equal( completableSpanState({ startsAt: inDays(60), endsAt: inDays(90), now, completedAt: now }), 'done', 'completion outranks the clock in both directions', ); }); }); describe('time zone validation', () => { it('separates a real zone from a plausible-looking string', () => { // The projection falls back to UTC for a stored zone it cannot use, which // is right for `users.timezone` and wrong for a query parameter: a caller // asking for a zone that does not exist should be told, not quietly // answered in UTC, and the formatter cache is keyed on this string. assert.equal(isValidTimeZone('Europe/London'), true); assert.equal(isValidTimeZone('UTC'), true); assert.equal(isValidTimeZone('Mars/Olympus'), false); assert.equal(isValidTimeZone(''), false); }); it('does not grow the formatter cache without bound', () => { // A loop over distinct values used to add one entry per value, for the // life of the process. Nothing observable should change from running it. for (let index = 0; index < 2000; index += 1) { quarterOf(new Date('2026-08-13T12:00:00.000Z'), 0, `Junk/Zone${index}`); } assert.equal( quarterOf(new Date('2027-01-01T00:30:00.000Z'), 0, 'America/New_York'), '2026-Q4', ); }); }); describe('event identity', () => { it('is stable without storage, and distinguishes fields on one record', () => { const id = calendarEventId('contract', 'c1', 'expiresAt'); assert.equal(id, 'contract:c1:expiresAt'); assert.notEqual(id, calendarEventId('contract', 'c1', 'effectiveAt')); }); it('exposes every kind through the guard', () => { for (const kind of CALENDAR_EVENT_KINDS) assert.ok(isCalendarEventKind(kind)); assert.equal(isCalendarEventKind('renewal'), false); }); });