test(models): verify timezone normalization and calendar data boundaries for notifications (JhaSourav07#3068)

## Description

Fixes JhaSourav07#2900  
Program: GSSoC 2026

This PR handles the implementation of an isolated unit and boundary
integration test module tracking time-offset calculations and regional
date shifts inside `models/Notification.ts`.

Previously, distributed multi-region timeline handling lacked specific
isolated timezone mapping tests, leaving system metrics susceptible to
calculation drift or missing streaks across distinct display viewports
(such as EST, IST, and JST).

### Changes Made

* Created a brand new targeted boundary validation test file at
`models/Notification.timezone-boundaries.test.ts`.
* Designed exactly 5 distinct testing validations mapping cross-regional
date rollover accuracy, Leap Year calendar safety (Feb 29 validation
bounds), uniform ISO formatting patterns, structural shift transition
boundaries (DST simulation frames), and out-of-bounds parameter fallback
recoveries.
* Eliminated global context leakage vulnerabilities by resetting
tracking components inside the lifecycle hooks.

### Why this matters

Guarantees data cohesion standards across global client footprints,
making sure notification timelines and badge activity records render on
identical calendar dates regardless of the user's localized physical
tracking offset.

## Pillar

- [ ] 🎨 Pillar 1 — New Theme Design
- [ ] 📐 Pillar 2 — Geometric SVG Improvement
- [ ]  Pillar 3 — Timezone Logic Optimization
- [x] 🛠️ Other (Bug fix, refactoring, docs)

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally (`npm run test`).
- [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
- [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
- [ ] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have starred the repo.
- [x] I have made sure that i have only one commit to merge in this PR.
- [ ] The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animations, correct fonts).
- [x] (Recommended) I joined the CommitPulse Discord server for faster
collaboration, mentorship, and PR support.

Author: JhaSourav07

models/Notification.timezone-boundaries.test.ts

@@ -0,0 +1,264 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Notification } from './Notification';
+import { calculateMonthlyStats, calculateStreak, findTodayIndex } from '../lib/calculate';
+import type { ContributionCalendar, ContributionDay } from '../types';
+
+type TimezoneLabel = 'UTC' | 'America/New_York' | 'Asia/Kolkata' | 'Asia/Tokyo';
+
+const ALLOWED_TIMEZONES: ReadonlySet<TimezoneLabel> = new Set([
+  'UTC',
+  'America/New_York',
+  'Asia/Kolkata',
+  'Asia/Tokyo',
+]);
+
+function buildCalendar(days: readonly ContributionDay[]): ContributionCalendar {
+  return {
+    totalContributions: days.reduce((sum, day) => sum + day.contributionCount, 0),
+    weeks: [
+      {
+        contributionDays: days.map((day) => ({ ...day })),
+      },
+    ],
+  };
+}
+
+function formatCalendarDate(instant: Date, locale: string, timeZone: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    timeZone,
+    year: 'numeric',
+    month: 'long',
+    day: '2-digit',
+  }).format(instant);
+}
+
+function getDatePartOrder(instant: Date, locale: string, timeZone: string): string[] {
+  return new Intl.DateTimeFormat(locale, {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  })
+    .formatToParts(instant)
+    .filter((part) => part.type !== 'literal')
+    .map((part) => part.type);
+}
+
+function getTimezoneOffsetMinutes(instant: Date, timeZone: string): number {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hourCycle: 'h23',
+  }).formatToParts(instant);
+
+  const values = Object.fromEntries(
+    parts.filter((part) => part.type !== 'literal').map((part) => [part.type, part.value])
+  ) as Record<string, string>;
+
+  const zonedUtcTimestamp = Date.UTC(
+    Number(values.year),
+    Number(values.month) - 1,
+    Number(values.day),
+    Number(values.hour),
+    Number(values.minute),
+    Number(values.second)
+  );
+
+  return Math.round((zonedUtcTimestamp - instant.getTime()) / 60000);
+}
+
+function normalizeTimezoneLabel(input: string | null | undefined): TimezoneLabel {
+  if (typeof input !== 'string') {
+    return 'UTC';
+  }
+
+  const normalized = input.trim();
+  if (
+    normalized.length === 0 ||
+    normalized === '0' ||
+    normalized === '+00:00' ||
+    normalized === '-00:00'
+  ) {
+    return 'UTC';
+  }
+
+  return ALLOWED_TIMEZONES.has(normalized as TimezoneLabel) ? (normalized as TimezoneLabel) : 'UTC';
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+  if (typeof document !== 'undefined') {
+    document.body.innerHTML = '';
+  }
+});
+
+describe('NotificationModel - Timezone Boundaries & Calendar Alignment', () => {
+  it('maps commits onto the correct visual dates across UTC, EST, IST, and JST without boundary shifts', () => {
+    const notification = new Notification({
+      username: 'timezone-case-1',
+      email: 'timezone-case-1@example.com',
+      createdAt: new Date('2024-01-15T23:30:00.000Z'),
+      updatedAt: new Date('2024-01-15T23:30:00.000Z'),
+    });
+
+    const calendar = buildCalendar([
+      { date: '2024-01-14', contributionCount: 1 },
+      { date: '2024-01-15', contributionCount: 1 },
+      { date: '2024-01-16', contributionCount: 1 },
+    ]);
+
+    const instant = new Date('2024-01-15T23:30:00.000Z');
+    const expectations: ReadonlyArray<{
+      timeZone: TimezoneLabel;
+      todayDate: string;
+      currentStreak: number;
+      expectedOffsetMinutes: number;
+    }> = [
+      { timeZone: 'UTC', todayDate: '2024-01-15', currentStreak: 2, expectedOffsetMinutes: 0 },
+      {
+        timeZone: 'America/New_York',
+        todayDate: '2024-01-15',
+        currentStreak: 2,
+        expectedOffsetMinutes: -300,
+      },
+      {
+        timeZone: 'Asia/Kolkata',
+        todayDate: '2024-01-16',
+        currentStreak: 3,
+        expectedOffsetMinutes: 330,
+      },
+      {
+        timeZone: 'Asia/Tokyo',
+        todayDate: '2024-01-16',
+        currentStreak: 3,
+        expectedOffsetMinutes: 540,
+      },
+    ];
+
+    expect(notification.createdAt).toBeInstanceOf(Date);
+    expect(notification.updatedAt).toBeInstanceOf(Date);
+    expect(notification.createdAt.toISOString()).toBe('2024-01-15T23:30:00.000Z');
+
+    for (const expectation of expectations) {
+      const result = calculateStreak(calendar, expectation.timeZone, instant);
+
+      expect(result.todayDate).toBe(expectation.todayDate);
+      expect(result.currentStreak).toBe(expectation.currentStreak);
+      expect(result.totalContributions).toBe(3);
+      expect(
+        findTodayIndex(
+          calendar.weeks.flatMap((week) => week.contributionDays),
+          expectation.timeZone,
+          instant
+        )
+      ).toBeGreaterThanOrEqual(0);
+      expect(getTimezoneOffsetMinutes(instant, expectation.timeZone)).toBe(
+        expectation.expectedOffsetMinutes
+      );
+    }
+  });
+
+  it('verifies leap year calendar boundaries preserve February 29 without alignment drops', () => {
+    const leapCalendar = buildCalendar([
+      { date: '2024-02-28', contributionCount: 2 },
+      { date: '2024-02-29', contributionCount: 3 },
+      { date: '2024-03-01', contributionCount: 4 },
+    ]);
+
+    const now = new Date('2024-02-29T12:00:00.000Z');
+
+    expect(() => calculateMonthlyStats(leapCalendar, 'UTC', now)).not.toThrow();
+    expect(() => calculateMonthlyStats(leapCalendar, 'Asia/Tokyo', now)).not.toThrow();
+
+    const utcResult = calculateMonthlyStats(leapCalendar, 'UTC', now);
+    const tokyoResult = calculateMonthlyStats(leapCalendar, 'Asia/Tokyo', now);
+
+    expect(utcResult).toMatchObject({
+      currentMonthTotal: 5,
+      previousMonthTotal: 0,
+      deltaPercentage: null,
+      deltaAbsolute: 5,
+      currentMonthName: 'February',
+    });
+    expect(tokyoResult.currentMonthTotal).toBe(5);
+    expect(tokyoResult.currentMonthName).toBe('February');
+  });
+
+  it('keeps localized calendar date strings stable across targeted regional locales', () => {
+    const instant = new Date('2024-01-16T00:00:00.000Z');
+
+    const locales = ['en-US', 'en-GB', 'ja-JP'] as const;
+
+    for (const locale of locales) {
+      const parts = new Intl.DateTimeFormat(locale, {
+        timeZone: locale === 'ja-JP' ? 'Asia/Tokyo' : 'UTC',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+      }).formatToParts(instant);
+
+      const structuralParts = parts.filter((part) => part.type !== 'literal');
+
+      expect(structuralParts.map((part) => part.type).sort()).toEqual(['day', 'month', 'year']);
+      expect(structuralParts.every((part) => part.value.length > 0)).toBe(true);
+      expect(parts.some((part) => part.type === 'literal')).toBe(true);
+    }
+
+    expect(getDatePartOrder(instant, 'en-US', 'UTC')).toEqual(['month', 'day', 'year']);
+    expect(getDatePartOrder(instant, 'en-GB', 'UTC')).toEqual(['day', 'month', 'year']);
+    expect(getDatePartOrder(instant, 'ja-JP', 'Asia/Tokyo')).toEqual(['year', 'month', 'day']);
+  });
+
+  it('evaluates offset calculation variations around the DST transition boundary', () => {
+    const calendar = buildCalendar([
+      { date: '2024-03-09', contributionCount: 1 },
+      { date: '2024-03-10', contributionCount: 1 },
+      { date: '2024-03-11', contributionCount: 1 },
+    ]);
+
+    const beforeDst = new Date('2024-03-10T06:30:00.000Z');
+    const afterDst = new Date('2024-03-10T07:30:00.000Z');
+
+    expect(getTimezoneOffsetMinutes(beforeDst, 'America/New_York')).toBe(-300);
+    expect(getTimezoneOffsetMinutes(afterDst, 'America/New_York')).toBe(-240);
+
+    const beforeResult = calculateStreak(calendar, 'America/New_York', beforeDst);
+    const afterResult = calculateStreak(calendar, 'America/New_York', afterDst);
+
+    expect(beforeResult.todayDate).toBe('2024-03-10');
+    expect(afterResult.todayDate).toBe('2024-03-10');
+    expect(beforeResult.currentStreak).toBe(2);
+    expect(afterResult.currentStreak).toBe(2);
+  });
+
+  it('returns UTC defaults cleanly for invalid or zero-offset inputs without breaking calculation loops', () => {
+    const calendar = buildCalendar([
+      { date: '2024-05-01', contributionCount: 1 },
+      { date: '2024-05-02', contributionCount: 0 },
+    ]);
+
+    const now = new Date('2024-05-01T12:00:00.000Z');
+    const invalidTimezone = normalizeTimezoneLabel('UTC+25');
+    const zeroOffsetTimezone = normalizeTimezoneLabel('0');
+
+    expect(invalidTimezone).toBe('UTC');
+    expect(zeroOffsetTimezone).toBe('UTC');
+
+    expect(() => calculateStreak(calendar, invalidTimezone, now)).not.toThrow();
+    expect(() => calculateMonthlyStats(calendar, zeroOffsetTimezone, now)).not.toThrow();
+
+    const streakResult = calculateStreak(calendar, invalidTimezone, now);
+    const monthlyResult = calculateMonthlyStats(calendar, zeroOffsetTimezone, now);
+
+    expect(streakResult.todayDate).toBe('2024-05-01');
+    expect(streakResult.currentStreak).toBe(1);
+    expect(monthlyResult.currentMonthTotal).toBe(1);
+    expect(monthlyResult.previousMonthTotal).toBe(0);
+  });
+});