test(StudentProfileModel-timezone-boundaries): verify Timezone Normalization & Calendar Data Boundary Alignment (Variation 8) (JhaSourav07#3177)

## Description

Closes JhaSourav07#2910

Adds the missing timezone normalisation and calendar data boundary
alignment coverage for `models/StudentProfile.ts`. The new test file
verifies the visual date mapping for `createdAt` / `updatedAt`, the
streak and monthly math across UTC, EST, IST, and JST, leap year
boundaries, localised date part ordering, DST transitions, and invalid
offset fallback behaviour.

## Pillar

- [x] 🛠️ Other (Test coverage for timezone normalisation & calendar data
boundary alignment)

## What changed

- Added `models/StudentProfile.timezone-boundaries.test.ts` with 5 test
cases covering:
- `createdAt` / `updatedAt` round-trip and visual date mapping for UTC,
America/New_York, Asia/Kolkata, and Asia/Tokyo
- Leap year boundary preservation (2024-02-29) across UTC and Asia/Tokyo
  - Localised calendar date part ordering across en-US, en-GB, and ja-JP
- DST transition offsets (2024-03-10 in America/New_York) and streak
continuity
- Invalid and zero-offset timezone labels normalised to UTC without
breaking calculation loops

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally (`npx vitest run
models/StudentProfile.timezone-boundaries.test.ts`).
- [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): ...`).
- [x] I have made sure that I have only one commit to merge in this PR.

## What this fixes

`models/StudentProfile.ts` did not have any test coverage verifying that
the timestamps attached to a profile (and the contribution calendar math
that depends on them) stay aligned when rendered in different timezones.
A profile created at the end of the day in UTC currently looks like it
was created the next day for viewers in IST or JST, and the
streak/monthly calculation routines in `lib/calculate.ts` are exactly
what power those visualisations, so any boundary shift there propagates
into the student profile surface.

## Root cause

The timezone offset handling only existed inside `calculateStreak`,
`calculateMonthlyStats`, and `findTodayIndex` in `lib/calculate.ts`. The
`StudentProfile` model itself does not perform any timezone
normalisation — it stores `createdAt` / `updatedAt` as raw `Date`
instances. That means the rendering layer (and any consumer that calls
the calendar helpers) is fully responsible for picking the right offset,
and the model had no regression net to catch a future change that moved
a date onto the wrong visual day (e.g. 2024-01-15 23:30 UTC being shown
as 2024-01-16 in Asia/Kolkata).

## How to verify

1. Checkout the branch: `git fetch && git checkout
test/student-profile-timezone-boundaries`
2. Install dependencies if needed: `npm install`
3. Run the new test file in isolation: `npx vitest run
models/StudentProfile.timezone-boundaries.test.ts`
4. Run the full suite to make sure nothing regresses: `npm test`
5. Run the lint/format gate: `npm run lint && npm run format:check`

## Edge cases considered

- **DST spring-forward**: covered via the `America/New_York` transition
on 2024-03-10. `calculateStreak` is expected to keep the streak alive
across the missing hour and report the same `todayDate` on both sides of
the transition.
- **Invalid timezone label**: `UTC+25`, `0`, `+00:00`, `-00:00`, and
empty strings are all normalised to `UTC` before being handed to the
calendar helpers so the streak/monthly routines do not throw.
- **Leap year boundary**: 2024-02-29 is included in the calendar and the
month name is asserted to remain `February` even when the viewer is in
`Asia/Tokyo`.
- **Localised date order**: `en-US` (`month/day/year`), `en-GB`
(`day/month/year`), and `ja-JP` (`year/month/day`) are all asserted so a
future i18n change is caught.
- **Out of scope**: The fix does not introduce any normalisation on the
model itself (e.g. writing back a timezone-normalised `createdAt`). That
is intentional — timezone is a presentation concern and the helpers in
`lib/calculate.ts` already accept it as a parameter.

Author: JhaSourav07

models/StudentProfile.timezone-boundaries.test.ts

@@ -0,0 +1,284 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { StudentProfile } from './StudentProfile';
+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('StudentProfileModel - Timezone Boundaries & Calendar Alignment', () => {
+  it('maps student profile createdAt and updatedAt onto the correct visual dates across UTC, EST, IST, and JST without boundary shifts', () => {
+    const profile = new StudentProfile({
+      githubUsername: 'timezone-case-1',
+      name: 'Timezone Tester',
+      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(profile.createdAt).toBeInstanceOf(Date);
+    expect(profile.updatedAt).toBeInstanceOf(Date);
+    expect(profile.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 for student profiles 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');
+
+    const profile = new StudentProfile({
+      githubUsername: 'leap-year-user',
+      name: 'Leap Year User',
+      email: 'leap@example.com',
+      graduationYear: 2024,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    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');
+    expect(profile.graduationYear).toBe(2024);
+  });
+
+  it('keeps localized calendar date strings stable across targeted regional locales for student profile timestamps', () => {
+    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 for student profile activity windows', () => {
+    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 timezone inputs on student profile queries 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');
+
+    const profile = new StudentProfile({
+      githubUsername: 'invalid-tz-user',
+      name: 'Invalid TZ User',
+      email: 'invalid-tz@example.com',
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    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);
+    expect(formatCalendarDate(profile.createdAt, 'en-US', invalidTimezone)).toBe('May 01, 2024');
+  });
+});