]*>0 = {}): Repo {
+ const id = overrides.id ?? nextRepoId++;
+ const name = overrides.name ?? `repo-${id}`;
+ const owner = overrides.owner?.login ?? "octo";
+ return {
+ id,
+ name,
+ full_name: `${owner}/${name}`,
+ description: null,
+ html_url: `https://github.com/${owner}/${name}`,
+ homepage: null,
+ language: "TypeScript",
+ stargazers_count: 0,
+ forks_count: 0,
+ archived: false,
+ private: false,
+ owner: { login: owner },
+ pushed_at: "2026-09-20T10:00:00Z",
+ updated_at: "2026-09-20T10:00:00Z",
+ topics: [],
+ ...overrides,
+ };
+}
+
+export function makeDays(
+ counts: number[],
+ startDate = "2026-09-01",
+): ContributionDay[] {
+ const start = new Date(`${startDate}T00:00:00.000Z`);
+ return counts.map((count, index) => {
+ const date = new Date(start);
+ date.setUTCDate(start.getUTCDate() + index);
+ return {
+ date: date.toISOString().slice(0, 10),
+ count,
+ level:
+ count === 0 ? 0 : count < 2 ? 1 : count < 4 ? 2 : count < 7 ? 3 : 4,
+ };
+ });
+}
+
+/**
+ * Builds the fragment of GitHub's contributions HTML that getContributionDays
+ * scrapes: a `` cell followed by a `` label.
+ */
+export function contributionsHtml(cells: Record) {
+ const rows = Object.entries(cells).map(([date, count]) => {
+ const label =
+ count === 0
+ ? `No contributions on ${date}`
+ : `${count} contribution${count === 1 ? "" : "s"} on ${date}`;
+ return ` | \n${label}`;
+ });
+ return ``;
+}
+
+export function jsonResponse(
+ body: unknown,
+ init: { status?: number; headers?: Record } = {},
+) {
+ return new Response(JSON.stringify(body), {
+ status: init.status ?? 200,
+ headers: { "content-type": "application/json", ...init.headers },
+ });
+}
+
+export function textResponse(body: string, status = 200) {
+ return new Response(body, {
+ status,
+ headers: { "content-type": "text/html" },
+ });
+}
+
+export type FetchRoute = {
+ match: (url: URL) => boolean;
+ respond: (url: URL, init?: RequestInit) => Response | Promise;
+};
+
+/**
+ * Replaces global fetch with a URL router. Any request that no route matches
+ * throws, so a test cannot quietly reach the real GitHub API or fall through to
+ * a fallback branch it did not mean to exercise.
+ */
+export function installFetchRouter(routes: FetchRoute[]) {
+ const calls: URL[] = [];
+ const fetchMock = vi.fn(
+ async (input: string | URL | Request, init?: RequestInit) => {
+ const url = new URL(
+ typeof input === "string"
+ ? input
+ : input instanceof URL
+ ? input.href
+ : input.url,
+ );
+ calls.push(url);
+ const route = routes.find((candidate) => candidate.match(url));
+ if (!route) {
+ throw new Error(`Unrouted fetch in test: ${url.href}`);
+ }
+ return route.respond(url, init);
+ },
+ );
+ vi.stubGlobal("fetch", fetchMock);
+ return { calls, fetchMock };
+}
+
+export const route = {
+ contributions: (username: string, html: string): FetchRoute => ({
+ match: (url) =>
+ url.hostname === "github.com" &&
+ url.pathname === `/users/${username}/contributions`,
+ respond: () => textResponse(html),
+ }),
+ authedRepos: (repos: Repo[]): FetchRoute => ({
+ match: (url) =>
+ url.hostname === "api.github.com" && url.pathname === "/user/repos",
+ respond: () => jsonResponse(repos),
+ }),
+ publicRepos: (username: string, repos: Repo[]): FetchRoute => ({
+ match: (url) =>
+ url.hostname === "api.github.com" &&
+ url.pathname === `/users/${username}/repos`,
+ respond: () => jsonResponse(repos),
+ }),
+ pinned: (nodes: unknown[]): FetchRoute => ({
+ match: (url) => url.pathname === "/graphql",
+ respond: () => jsonResponse({ data: { user: { pinnedItems: { nodes } } } }),
+ }),
+ commits: (
+ byFullName: Record,
+ options: { requireAuthor?: string } = {},
+ ): FetchRoute => ({
+ match: (url) => /^\/repos\/[^/]+\/[^/]+\/commits$/.test(url.pathname),
+ respond: (url) => {
+ if (
+ options.requireAuthor &&
+ url.searchParams.get("author") !== options.requireAuthor
+ ) {
+ return jsonResponse([]);
+ }
+ const fullName = url.pathname
+ .replace(/^\/repos\//, "")
+ .replace(/\/commits$/, "");
+ // The real endpoint only returns commits at or after `since`.
+ const since = url.searchParams.get("since");
+ const dates = (byFullName[fullName] ?? []).filter(
+ (date) => !since || date >= since,
+ );
+ return jsonResponse(
+ dates.map((date) => ({ commit: { author: { date } } })),
+ );
+ },
+ }),
+ searchCount: (countFor: (query: string) => number): FetchRoute => ({
+ match: (url) => url.pathname === "/search/issues",
+ respond: (url) =>
+ jsonResponse({ total_count: countFor(url.searchParams.get("q") ?? "") }),
+ }),
+};
+
+export const extraRoutes = {
+ pulls: (
+ byFullName: Record<
+ string,
+ Array<{
+ created_at: string;
+ updated_at: string;
+ merged_at: string | null;
+ user: { login: string };
+ }>
+ >,
+ ): FetchRoute => ({
+ match: (url) => /^\/repos\/[^/]+\/[^/]+\/pulls$/.test(url.pathname),
+ respond: (url) => {
+ const fullName = url.pathname
+ .replace(/^\/repos\//, "")
+ .replace(/\/pulls$/, "");
+ return jsonResponse(byFullName[fullName] ?? []);
+ },
+ }),
+ releases: (
+ byFullName: Record>,
+ ): FetchRoute => ({
+ match: (url) => /^\/repos\/[^/]+\/[^/]+\/releases$/.test(url.pathname),
+ respond: (url) => {
+ const fullName = url.pathname
+ .replace(/^\/repos\//, "")
+ .replace(/\/releases$/, "");
+ return jsonResponse(byFullName[fullName] ?? []);
+ },
+ }),
+};
+
+/**
+ * Drives a promise to completion under fake timers by advancing the clock in
+ * steps. lib/github.ts spaces GitHub Search calls out with setTimeout, so a
+ * test that awaited the promise directly would hang.
+ */
+export async function settle(
+ promise: Promise,
+ stepMs = 500,
+ maxSteps = 400,
+): Promise {
+ type Outcome = { ok: true; value: T } | { ok: false; error: unknown };
+ // Held in an object because the assignment happens inside a callback,
+ // which TypeScript's control-flow narrowing cannot see.
+ const box: { outcome: Outcome | null } = { outcome: null };
+ const tracked = promise.then(
+ (value) => {
+ box.outcome = { ok: true, value };
+ },
+ (error: unknown) => {
+ box.outcome = { ok: false, error };
+ },
+ );
+ for (let step = 0; step < maxSteps && box.outcome === null; step += 1) {
+ await vi.advanceTimersByTimeAsync(stepMs);
+ }
+ await tracked;
+ if (box.outcome === null) {
+ throw new Error(`Promise did not settle within ${maxSteps * stepMs}ms`);
+ }
+ if (box.outcome.ok) {
+ return box.outcome.value;
+ }
+ throw box.outcome.error;
+}
diff --git a/tests/lib/contribution-shaping.test.ts b/tests/lib/contribution-shaping.test.ts
new file mode 100644
index 0000000..b0cb1eb
--- /dev/null
+++ b/tests/lib/contribution-shaping.test.ts
@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ buildCalendarCells,
+ buildLast30Days,
+ buildRepoPushCadence,
+ buildSparklinePoints,
+ buildWeeklyTotals,
+ chunkWeeks,
+ currentStreak,
+ daysSince,
+ formatRepoDate,
+ levelForCount,
+ longestStreak,
+ prettyDay,
+ prettyLongDay,
+} from "@/lib/github";
+import { FROZEN_NOW, makeDays, makeRepo } from "../helpers/github-fixtures";
+
+// Every function here derives its window from "today", so the clock is frozen
+// at 2026-09-25 (a Friday) and the 30-day window runs 2026-08-27 .. 2026-09-25.
+beforeEach(() => {
+ vi.useFakeTimers({ now: FROZEN_NOW, toFake: ["Date"] });
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+});
+
+describe("levelForCount", () => {
+ it.each([
+ [0, 0],
+ [1, 1],
+ [2, 2],
+ [3, 2],
+ [4, 3],
+ [6, 3],
+ [7, 4],
+ [40, 4],
+ ])("maps %i contributions to heatmap level %i", (count, level) => {
+ expect(levelForCount(count)).toBe(level);
+ });
+});
+
+describe("streaks", () => {
+ it("longestStreak finds the longest run of active days", () => {
+ expect(longestStreak(makeDays([1, 2, 0, 3, 4, 5, 0]))).toBe(3);
+ });
+
+ it("longestStreak is 0 for no days or no activity", () => {
+ expect(longestStreak([])).toBe(0);
+ expect(longestStreak(makeDays([0, 0, 0]))).toBe(0);
+ });
+
+ it("currentStreak counts back from the most recent day", () => {
+ expect(currentStreak(makeDays([1, 1, 0, 2, 3]))).toBe(2);
+ });
+
+ it("currentStreak is 0 when the most recent day is quiet", () => {
+ expect(currentStreak(makeDays([4, 4, 4, 0]))).toBe(0);
+ });
+});
+
+describe("buildLast30Days", () => {
+ it("returns 30 consecutive ISO dates ending today", () => {
+ const dates = buildLast30Days();
+ expect(dates).toHaveLength(30);
+ expect(dates[0]).toBe("2026-08-27");
+ expect(dates.at(-1)).toBe("2026-09-25");
+ for (let index = 1; index < dates.length; index += 1) {
+ const previous = new Date(`${dates[index - 1]}T00:00:00Z`).getTime();
+ const current = new Date(`${dates[index]}T00:00:00Z`).getTime();
+ expect(current - previous).toBe(86_400_000);
+ }
+ });
+});
+
+describe("calendar layout", () => {
+ it("buildCalendarCells pads to full Sunday-to-Saturday weeks", () => {
+ // 2026-09-23 is a Wednesday, 2026-09-25 a Friday.
+ const cells = buildCalendarCells(makeDays([1, 1, 1], "2026-09-23"));
+ expect(cells).toHaveLength(7);
+ expect(cells.slice(0, 3)).toEqual([null, null, null]);
+ expect(cells[3]?.date).toBe("2026-09-23");
+ expect(cells[6]).toBeNull();
+ });
+
+ it("buildCalendarCells returns nothing for no days", () => {
+ expect(buildCalendarCells([])).toEqual([]);
+ });
+
+ it("chunkWeeks splits cells into rows of seven", () => {
+ const cells = buildCalendarCells(makeDays(Array(30).fill(1), "2026-08-27"));
+ const weeks = chunkWeeks(cells);
+ expect(weeks).toHaveLength(5);
+ expect(weeks.every((week) => week.length === 7)).toBe(true);
+ expect(chunkWeeks(cells.slice(0, 8)).map((week) => week.length)).toEqual([
+ 7, 1,
+ ]);
+ });
+
+ it("buildWeeklyTotals sums each calendar week and labels its range", () => {
+ const counts = Array.from({ length: 30 }, (_, index) => index + 1);
+ const weeks = buildWeeklyTotals(makeDays(counts, "2026-08-27"));
+
+ expect(weeks.map((week) => week.label)).toEqual([
+ "Week 1",
+ "Week 2",
+ "Week 3",
+ "Week 4",
+ "Week 5",
+ ]);
+ // Thu 27 .. Sat 29 Aug -> 1 + 2 + 3
+ expect(weeks[0]).toMatchObject({ total: 6, range: "Aug 27 – Aug 29" });
+ // Sun 20 .. Fri 25 Sep -> 25 + ... + 30
+ expect(weeks[4]).toMatchObject({ total: 165, range: "Sep 20 – Sep 25" });
+ expect(weeks.reduce((sum, week) => sum + week.total, 0)).toBe(465);
+ });
+
+ it("buildWeeklyTotals returns nothing for no days", () => {
+ expect(buildWeeklyTotals([])).toEqual([]);
+ });
+});
+
+describe("buildSparklinePoints", () => {
+ it("scales counts into the 260x72 viewBox with 6px padding", () => {
+ expect(buildSparklinePoints(makeDays([0, 5, 10]))).toBe(
+ "6,66 130,36 254,6",
+ );
+ });
+});
+
+describe("buildRepoPushCadence", () => {
+ it("counts repos pushed inside each weekly window of the 30-day range", () => {
+ const repos = [
+ makeRepo({ pushed_at: "2026-08-27T00:00:00Z" }), // first window, first ms
+ makeRepo({ pushed_at: "2026-09-04T10:00:00Z" }), // second window
+ makeRepo({ pushed_at: "2026-09-25T23:59:59Z" }), // last window, last second
+ makeRepo({ pushed_at: "2026-08-01T00:00:00Z" }), // before the window
+ ];
+
+ const cadence = buildRepoPushCadence(repos);
+
+ expect(cadence.map((point) => point.value)).toEqual([1, 1, 0, 0, 1]);
+ expect(cadence.map((point) => point.label)).toEqual([
+ "Aug 27",
+ "Sep 3",
+ "Sep 10",
+ "Sep 17",
+ "Sep 24",
+ ]);
+ expect(cadence.map((point) => point.index)).toEqual([1, 2, 3, 4, 5]);
+ expect(cadence.at(-1)?.range).toBe("Sep 24 – Sep 25");
+ });
+});
+
+describe("date helpers", () => {
+ it("daysSince floors to whole days and never goes negative", () => {
+ expect(daysSince("2026-09-20T12:00:00Z")).toBe(5);
+ expect(daysSince("2026-09-25T13:00:00Z")).toBe(0);
+ expect(daysSince("not a date")).toBe(0);
+ });
+
+ it("formats dates the way the cards show them", () => {
+ expect(formatRepoDate("2026-09-20T10:00:00Z")).toBe("Sep 20, 2026");
+ expect(prettyDay("2026-09-05")).toBe("Sep 5");
+ expect(prettyLongDay("2026-09-05")).toBe("September 5, 2026");
+ });
+});
diff --git a/tests/lib/github-api.test.ts b/tests/lib/github-api.test.ts
new file mode 100644
index 0000000..68efcbe
--- /dev/null
+++ b/tests/lib/github-api.test.ts
@@ -0,0 +1,552 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ buildRepoCommitActivitySummary,
+ getCommitTimingHeatmap,
+ getContributionDays,
+ getIssueFlowHealth,
+ getPinnedRepos,
+ getPullRequestHealth,
+ getReleaseCadence,
+ getRepoRiskSnapshot,
+ getRepos,
+} from "@/lib/github";
+import {
+ contributionsHtml,
+ extraRoutes,
+ FROZEN_NOW,
+ installFetchRouter,
+ jsonResponse,
+ makeRepo,
+ route,
+ settle,
+ textResponse,
+} from "../helpers/github-fixtures";
+
+// The clock is frozen at 2026-09-25 so the weekly windows are
+// Aug 27-Sep 2, Sep 3-9, Sep 10-16, Sep 17-23 and Sep 24-25.
+// Only Date and setTimeout are faked: the search rate limiter sleeps with
+// setTimeout, and nothing else in the module depends on timers.
+beforeEach(() => {
+ vi.useFakeTimers({
+ now: FROZEN_NOW,
+ toFake: ["Date", "setTimeout", "clearTimeout"],
+ });
+ vi.spyOn(console, "error").mockImplementation(() => undefined);
+ vi.spyOn(console, "warn").mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+});
+
+describe("getContributionDays", () => {
+ it("scrapes the contribution calendar into a zero-filled 30-day series", async () => {
+ const { calls } = installFetchRouter([
+ route.contributions(
+ "octo",
+ contributionsHtml({
+ "2026-08-27": 8,
+ "2026-09-01": 1,
+ "2026-09-24": 0,
+ "2026-09-25": 3,
+ }),
+ ),
+ ]);
+
+ const days = await getContributionDays("octo");
+
+ expect(calls[0].searchParams.get("from")).toBe("2026-08-27");
+ expect(calls[0].searchParams.get("to")).toBe("2026-09-25");
+ expect(days).toHaveLength(30);
+ expect(days[0]).toEqual({ date: "2026-08-27", count: 8, level: 4 });
+ expect(days.at(-1)).toEqual({ date: "2026-09-25", count: 3, level: 2 });
+ expect(days.find((day) => day.date === "2026-09-01")).toEqual({
+ date: "2026-09-01",
+ count: 1,
+ level: 1,
+ });
+ // Days GitHub did not list, and days labelled "No contributions", are 0.
+ expect(days.find((day) => day.date === "2026-09-10")?.count).toBe(0);
+ expect(days.find((day) => day.date === "2026-09-24")?.count).toBe(0);
+ });
+
+ it("degrades to an all-zero series when GitHub rate-limits the page", async () => {
+ installFetchRouter([
+ {
+ match: (url) => url.pathname.endsWith("/contributions"),
+ respond: () => textResponse("", 403),
+ },
+ ]);
+
+ const days = await getContributionDays("octo");
+
+ expect(days).toHaveLength(30);
+ expect(days.every((day) => day.count === 0 && day.level === 0)).toBe(true);
+ });
+
+ it("throws on any other upstream failure", async () => {
+ installFetchRouter([
+ {
+ match: (url) => url.pathname.endsWith("/contributions"),
+ respond: () => textResponse("", 500),
+ },
+ ]);
+
+ await expect(getContributionDays("octo")).rejects.toThrow(/500/);
+ });
+});
+
+describe("getRepos", () => {
+ it("uses the authenticated endpoint and keeps only the user's active repos", async () => {
+ const { calls } = installFetchRouter([
+ route.authedRepos([
+ makeRepo({ name: "mine" }),
+ makeRepo({ name: "mine-archived", archived: true }),
+ makeRepo({ name: "theirs", owner: { login: "someone-else" } }),
+ {
+ ...makeRepo({ name: "legacy-shape" }),
+ owner: undefined,
+ full_name: "octo/legacy-shape",
+ },
+ ]),
+ ]);
+
+ const repos = await getRepos("octo");
+
+ expect(calls[0].pathname).toBe("/user/repos");
+ expect(calls[0].searchParams.get("visibility")).toBe("all");
+ expect(repos.map((repo) => repo.name)).toEqual(["mine", "legacy-shape"]);
+ });
+
+ it("follows Link rel=next pagination", async () => {
+ installFetchRouter([
+ {
+ match: (url) => url.pathname === "/user/repos",
+ respond: (url) =>
+ url.searchParams.get("page") === "2"
+ ? jsonResponse([makeRepo({ name: "page-two" })])
+ : jsonResponse([makeRepo({ name: "page-one" })], {
+ headers: {
+ link: '; rel="next", ; rel="last"',
+ },
+ }),
+ },
+ ]);
+
+ const repos = await getRepos("octo");
+
+ expect(repos.map((repo) => repo.name)).toEqual(["page-one", "page-two"]);
+ });
+
+ it("falls back to the public listing when the token is rejected", async () => {
+ const { calls } = installFetchRouter([
+ {
+ match: (url) => url.pathname === "/user/repos",
+ respond: () =>
+ jsonResponse({ message: "Bad credentials" }, { status: 401 }),
+ },
+ route.publicRepos("octo", [
+ makeRepo({ name: "public" }),
+ makeRepo({ name: "public-archived", archived: true }),
+ ]),
+ ]);
+
+ const repos = await getRepos("octo");
+
+ expect(calls.map((url) => url.pathname)).toEqual([
+ "/user/repos",
+ "/users/octo/repos",
+ ]);
+ expect(repos.map((repo) => repo.name)).toEqual(["public"]);
+ });
+
+ it("returns an empty list when both endpoints are rate-limited", async () => {
+ installFetchRouter([
+ {
+ match: (url) => url.pathname.endsWith("/repos"),
+ respond: () =>
+ jsonResponse({ message: "rate limited" }, { status: 403 }),
+ },
+ ]);
+
+ await expect(getRepos("octo")).resolves.toEqual([]);
+ });
+
+ it("goes straight to the public listing without a token", async () => {
+ vi.stubEnv("GITHUB_TOKEN", "");
+ const { calls } = installFetchRouter([
+ route.publicRepos("octo", [makeRepo({ name: "public" })]),
+ ]);
+
+ const repos = await getRepos("octo");
+
+ expect(calls.map((url) => url.pathname)).toEqual(["/users/octo/repos"]);
+ expect(repos.map((repo) => repo.name)).toEqual(["public"]);
+ });
+});
+
+describe("getPinnedRepos", () => {
+ const pinnedNode = {
+ id: "R_1",
+ databaseId: 11,
+ name: "alpha",
+ nameWithOwner: "octo/alpha",
+ description: "First project",
+ url: "https://github.com/octo/alpha",
+ homepageUrl: "https://alpha.example.com",
+ primaryLanguage: { name: "TypeScript" },
+ stargazerCount: 5,
+ forkCount: 1,
+ isArchived: false,
+ isPrivate: false,
+ pushedAt: "2026-09-20T10:00:00Z",
+ updatedAt: "2026-09-21T10:00:00Z",
+ repositoryTopics: { nodes: [{ topic: { name: "nextjs" } }, { topic: {} }] },
+ owner: { login: "octo" },
+ };
+
+ it("maps GraphQL pinned items onto the REST repo shape", async () => {
+ installFetchRouter([
+ route.pinned([
+ pinnedNode,
+ { ...pinnedNode, databaseId: 12, name: "old", isArchived: true },
+ { ...pinnedNode, databaseId: null, name: "no-id" },
+ ]),
+ ]);
+
+ const repos = await getPinnedRepos("octo");
+
+ expect(repos).toHaveLength(1);
+ expect(repos[0]).toMatchObject({
+ id: 11,
+ name: "alpha",
+ full_name: "octo/alpha",
+ html_url: "https://github.com/octo/alpha",
+ homepage: "https://alpha.example.com",
+ language: "TypeScript",
+ stargazers_count: 5,
+ forks_count: 1,
+ archived: false,
+ private: false,
+ pushed_at: "2026-09-20T10:00:00Z",
+ updated_at: "2026-09-21T10:00:00Z",
+ topics: ["nextjs"],
+ });
+ });
+
+ it("throws when GraphQL reports errors", async () => {
+ installFetchRouter([
+ {
+ match: (url) => url.pathname === "/graphql",
+ respond: () => jsonResponse({ errors: [{ message: "nope" }] }),
+ },
+ ]);
+
+ await expect(getPinnedRepos("octo")).rejects.toThrow(/GraphQL/);
+ });
+
+ it("refuses to run without a token instead of returning nothing", async () => {
+ vi.stubEnv("GITHUB_TOKEN", "");
+ installFetchRouter([]);
+
+ await expect(getPinnedRepos("octo")).rejects.toThrow(/authentication/i);
+ });
+});
+
+describe("buildRepoCommitActivitySummary", () => {
+ it("fetches commits only for the top repos, buckets them by week and ranks repos", async () => {
+ const hot = makeRepo({
+ name: "a-very-long-repository-name",
+ pushed_at: "2026-09-24T10:00:00Z",
+ });
+ const warm = makeRepo({ name: "warm", pushed_at: "2026-09-10T10:00:00Z" });
+ const cold = makeRepo({ name: "cold", pushed_at: "2026-08-01T10:00:00Z" });
+ const pinnedOld = makeRepo({
+ name: "pinned-old",
+ pushed_at: "2026-07-01T10:00:00Z",
+ });
+ const { calls } = installFetchRouter([
+ route.commits({
+ [hot.full_name]: [
+ "2026-09-24T09:00:00Z",
+ "2026-09-04T09:00:00Z",
+ "2026-08-01T00:00:00Z",
+ ],
+ [pinnedOld.full_name]: ["2026-09-25T01:00:00Z"],
+ }),
+ ]);
+
+ const summary = await buildRepoCommitActivitySummary(
+ [cold, warm, hot, pinnedOld],
+ 2,
+ { forceIncludeFullNames: [pinnedOld.full_name] },
+ );
+
+ expect(
+ calls.map((url) => url.pathname.replace(/^\/repos\//, "")).sort(),
+ ).toEqual([`${hot.full_name}/commits`, `${pinnedOld.full_name}/commits`]);
+ expect(calls[0].searchParams.get("since")).toBe("2026-08-27T00:00:00Z");
+ expect(summary.weekly.map((week) => week.value)).toEqual([0, 1, 0, 0, 2]);
+ expect(summary.weekly.map((week) => week.index)).toEqual([1, 2, 3, 4, 5]);
+ expect(summary.perRepo).toEqual([
+ {
+ name: "a-very-long-re…",
+ fullName: hot.full_name,
+ commits: 2,
+ pushedAt: hot.pushed_at,
+ },
+ {
+ name: "pinned-old",
+ fullName: pinnedOld.full_name,
+ commits: 1,
+ pushedAt: pinnedOld.pushed_at,
+ },
+ ]);
+ });
+
+ it("returns empty weekly buckets without calling GitHub when there are no repos", async () => {
+ const { fetchMock } = installFetchRouter([]);
+
+ const summary = await buildRepoCommitActivitySummary([], 8);
+
+ expect(fetchMock).not.toHaveBeenCalled();
+ expect(summary.weekly.map((week) => week.value)).toEqual([0, 0, 0, 0, 0]);
+ expect(summary.perRepo).toEqual([]);
+ });
+});
+
+describe("getCommitTimingHeatmap", () => {
+ it("buckets commits by weekday and hour in the requested timezone", async () => {
+ installFetchRouter([
+ route.authedRepos([
+ makeRepo({ name: "heat", owner: { login: "octo-heat" } }),
+ ]),
+ route.commits(
+ {
+ "octo-heat/heat": [
+ "2026-09-21T03:30:00Z", // Mon 03:30 UTC = Sun 20:30 in Los Angeles
+ "2026-09-21T03:45:00Z",
+ "2026-09-22T15:00:00Z", // Tue 15:00 UTC = Tue 08:00 in Los Angeles
+ "not-a-date",
+ ],
+ },
+ { requireAuthor: "octo-heat" },
+ ),
+ ]);
+
+ const heatmap = await getCommitTimingHeatmap(
+ "America/Los_Angeles",
+ "octo-heat",
+ );
+
+ expect(heatmap.timezone).toBe("America/Los_Angeles");
+ expect(heatmap.totalCommits).toBe(3);
+ expect(heatmap.maxCellCount).toBe(2);
+ expect(heatmap.cells).toHaveLength(7 * 24);
+ const sundayEvening = heatmap.cells.find(
+ (cell) => cell.dayIndex === 0 && cell.hour === 20,
+ );
+ expect(sundayEvening).toMatchObject({
+ dayLabel: "Sun",
+ hourLabel: "20:00",
+ count: 2,
+ intensity: 4,
+ });
+ expect(
+ heatmap.cells.find((cell) => cell.dayIndex === 2 && cell.hour === 8),
+ ).toMatchObject({ dayLabel: "Tue", count: 1, intensity: 2 });
+ expect(heatmap.cells.filter((cell) => cell.count > 0)).toHaveLength(2);
+ });
+
+ it("falls back to UTC for an unknown timezone", async () => {
+ installFetchRouter([
+ route.authedRepos([
+ makeRepo({ name: "heat", owner: { login: "octo-heat-2" } }),
+ ]),
+ route.commits(
+ { "octo-heat-2/heat": ["2026-09-21T03:30:00Z"] },
+ { requireAuthor: "octo-heat-2" },
+ ),
+ ]);
+
+ const heatmap = await getCommitTimingHeatmap("Not/AZone", "octo-heat-2");
+
+ expect(heatmap.timezone).toBe("UTC");
+ expect(
+ heatmap.cells.find((cell) => cell.dayIndex === 1 && cell.hour === 3),
+ ).toMatchObject({ dayLabel: "Mon", count: 1, intensity: 4 });
+ });
+});
+
+describe("getRepoRiskSnapshot", () => {
+ it("assigns active repos to freshness buckets and excludes archived ones", async () => {
+ const owner = { login: "octo-risk" };
+ installFetchRouter([
+ route.authedRepos([
+ makeRepo({ name: "hot", owner, pushed_at: "2026-09-22T10:00:00Z" }),
+ makeRepo({
+ name: "hot-private",
+ owner,
+ private: true,
+ pushed_at: "2026-09-25T10:00:00Z",
+ }),
+ makeRepo({ name: "active", owner, pushed_at: "2026-09-10T10:00:00Z" }),
+ makeRepo({ name: "stale", owner, pushed_at: "2026-08-01T10:00:00Z" }),
+ makeRepo({ name: "dormant", owner, pushed_at: "2026-01-01T10:00:00Z" }),
+ makeRepo({
+ name: "archived",
+ owner,
+ archived: true,
+ pushed_at: "2026-09-24T10:00:00Z",
+ }),
+ ]),
+ ]);
+
+ const snapshot = await getRepoRiskSnapshot("octo-risk");
+
+ expect(snapshot).toEqual({
+ totalRepos: 5,
+ archivedRepos: 1,
+ privateRepos: 1,
+ atRiskRepos: 2,
+ buckets: [
+ { label: "Hot (0-7d)", count: 2 },
+ { label: "Active (8-30d)", count: 1 },
+ { label: "Stale (31-89d)", count: 1 },
+ { label: "Dormant (90d+)", count: 1 },
+ ],
+ });
+ });
+});
+
+describe("getReleaseCadence", () => {
+ it("counts published releases per calendar month across the window", async () => {
+ installFetchRouter([
+ route.authedRepos([
+ makeRepo({ name: "lib", owner: { login: "octo-rel" } }),
+ ]),
+ extraRoutes.releases({
+ "octo-rel/lib": [
+ { published_at: "2026-09-20T00:00:00Z" },
+ { published_at: "2026-09-02T00:00:00Z" },
+ { published_at: "2026-07-15T00:00:00Z" },
+ { published_at: null }, // draft
+ { published_at: "2025-12-01T00:00:00Z" }, // before the window
+ ],
+ }),
+ ]);
+
+ const cadence = await getReleaseCadence("octo-rel", 6);
+
+ expect(cadence.map((point) => point.label)).toEqual([
+ "Apr",
+ "May",
+ "Jun",
+ "Jul",
+ "Aug",
+ "Sep",
+ ]);
+ expect(cadence.map((point) => point.monthKey)).toEqual([
+ "2026-04",
+ "2026-05",
+ "2026-06",
+ "2026-07",
+ "2026-08",
+ "2026-09",
+ ]);
+ expect(cadence.map((point) => point.releases)).toEqual([0, 0, 0, 1, 0, 2]);
+ });
+});
+
+describe("getPullRequestHealth", () => {
+ it("derives weekly merge rate and median cycle time from the user's merged PRs", async () => {
+ installFetchRouter([
+ route.searchCount((query) => {
+ if (query.includes("merged:")) return 3;
+ return 4; // created and closed
+ }),
+ route.authedRepos([
+ makeRepo({ name: "repo-x", owner: { login: "octo-pr" } }),
+ ]),
+ extraRoutes.pulls({
+ "octo-pr/repo-x": [
+ {
+ created_at: "2026-09-10T00:00:00Z",
+ updated_at: "2026-09-11T00:00:00Z",
+ merged_at: "2026-09-11T00:00:00Z", // 24h, third week
+ user: { login: "Octo-PR" }, // login case must not matter
+ },
+ {
+ created_at: "2026-09-12T00:00:00Z",
+ updated_at: "2026-09-12T06:00:00Z",
+ merged_at: "2026-09-12T06:00:00Z", // 6h, third week
+ user: { login: "octo-pr" },
+ },
+ {
+ created_at: "2026-09-12T00:00:00Z",
+ updated_at: "2026-09-12T01:00:00Z",
+ merged_at: "2026-09-12T01:00:00Z",
+ user: { login: "someone-else" }, // not the author we measure
+ },
+ {
+ created_at: "2026-09-13T00:00:00Z",
+ updated_at: "2026-09-13T00:00:00Z",
+ merged_at: null, // closed without merging
+ user: { login: "octo-pr" },
+ },
+ {
+ created_at: "2026-06-30T00:00:00Z",
+ updated_at: "2026-07-01T00:00:00Z",
+ merged_at: "2026-07-01T00:00:00Z", // before the window
+ user: { login: "octo-pr" },
+ },
+ ],
+ }),
+ ]);
+
+ const weeks = await settle(getPullRequestHealth("octo-pr"));
+
+ expect(weeks).toHaveLength(5);
+ expect(weeks[2]).toEqual({
+ label: "Sep 10",
+ range: "Sep 10 – Sep 16",
+ opened: 4,
+ merged: 3,
+ closed: 4,
+ reopened: 0,
+ mergeRate: 75,
+ reopenRate: 0,
+ medianCycleHours: 15,
+ cycleSampleSize: 2,
+ });
+ for (const index of [0, 1, 3, 4]) {
+ expect(weeks[index]).toMatchObject({
+ medianCycleHours: 0,
+ cycleSampleSize: 0,
+ mergeRate: 75,
+ });
+ }
+ });
+});
+
+describe("getIssueFlowHealth", () => {
+ it("accumulates the net backlog delta week over week", async () => {
+ installFetchRouter([
+ route.searchCount((query) => (query.includes("closed:") ? 1 : 3)),
+ ]);
+
+ const weeks = await settle(getIssueFlowHealth("octo-issues"));
+
+ expect(weeks.map((week) => week.label)).toEqual([
+ "Aug 27",
+ "Sep 3",
+ "Sep 10",
+ "Sep 17",
+ "Sep 24",
+ ]);
+ expect(weeks.map((week) => [week.opened, week.closed])).toEqual(
+ Array(5).fill([3, 1]),
+ );
+ expect(weeks.map((week) => week.backlogDelta)).toEqual([2, 4, 6, 8, 10]);
+ });
+});
diff --git a/tests/lib/site-helpers.test.ts b/tests/lib/site-helpers.test.ts
new file mode 100644
index 0000000..402a916
--- /dev/null
+++ b/tests/lib/site-helpers.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+ getConfiguredActivityTimezone,
+ sanitizeTimezone,
+} from "@/lib/timezone";
+import { normalizeHttpUrl } from "@/lib/url";
+
+describe("sanitizeTimezone", () => {
+ it("accepts IANA names and trims whitespace", () => {
+ expect(sanitizeTimezone("America/New_York")).toBe("America/New_York");
+ expect(sanitizeTimezone(" UTC ")).toBe("UTC");
+ });
+
+ it("rejects unknown or empty values", () => {
+ expect(sanitizeTimezone("Mars/Olympus")).toBeNull();
+ expect(sanitizeTimezone("")).toBeNull();
+ expect(sanitizeTimezone(undefined)).toBeNull();
+ });
+});
+
+describe("getConfiguredActivityTimezone", () => {
+ it("reads the server-side variable first", () => {
+ vi.stubEnv("ACTIVITY_HEATMAP_TIMEZONE", "Europe/Berlin");
+ vi.stubEnv("NEXT_PUBLIC_ACTIVITY_HEATMAP_TIMEZONE", "Asia/Tokyo");
+ expect(getConfiguredActivityTimezone()).toBe("Europe/Berlin");
+ });
+
+ it("falls back to the public variable, then to UTC", () => {
+ vi.stubEnv("ACTIVITY_HEATMAP_TIMEZONE", undefined);
+ vi.stubEnv("NEXT_PUBLIC_ACTIVITY_HEATMAP_TIMEZONE", "Asia/Tokyo");
+ expect(getConfiguredActivityTimezone()).toBe("Asia/Tokyo");
+
+ vi.stubEnv("NEXT_PUBLIC_ACTIVITY_HEATMAP_TIMEZONE", "Nowhere/Real");
+ expect(getConfiguredActivityTimezone()).toBe("UTC");
+ });
+});
+
+describe("normalizeHttpUrl", () => {
+ it("adds https to bare hosts and keeps http(s) URLs", () => {
+ expect(normalizeHttpUrl("example.com")).toBe("https://example.com/");
+ expect(normalizeHttpUrl("https://alpha.example.com/docs")).toBe(
+ "https://alpha.example.com/docs",
+ );
+ expect(normalizeHttpUrl("http://localhost:3000")).toBe(
+ "http://localhost:3000/",
+ );
+ });
+
+ it("refuses anything that is not a web URL, so repo homepages cannot inject other schemes", () => {
+ expect(normalizeHttpUrl("javascript:alert(1)")).toBeNull();
+ expect(normalizeHttpUrl("ftp://files.example.com")).toBeNull();
+ expect(normalizeHttpUrl("not a url")).toBeNull();
+ expect(normalizeHttpUrl("")).toBeNull();
+ expect(normalizeHttpUrl(null)).toBeNull();
+ });
+});
+
+describe("getPublicSiteUrl", () => {
+ async function loadFresh() {
+ vi.resetModules();
+ return (await import("@/lib/site-config")).getPublicSiteUrl;
+ }
+
+ it("strips trailing slashes from the configured URL", async () => {
+ vi.stubEnv("NEXT_PUBLIC_SITE_URL", "https://github.brandonperfetti.com/");
+ const getPublicSiteUrl = await loadFresh();
+ expect(getPublicSiteUrl()).toBe("https://github.brandonperfetti.com");
+ });
+
+ it("falls back to localhost only in development", async () => {
+ vi.stubEnv("NEXT_PUBLIC_SITE_URL", undefined);
+ vi.stubEnv("NODE_ENV", "development");
+ const getPublicSiteUrl = await loadFresh();
+ expect(getPublicSiteUrl()).toBe("http://localhost:3000");
+ });
+
+ it("throws outside development when the URL is missing", async () => {
+ vi.stubEnv("NEXT_PUBLIC_SITE_URL", undefined);
+ vi.stubEnv("NODE_ENV", "production");
+ const getPublicSiteUrl = await loadFresh();
+ expect(() => getPublicSiteUrl()).toThrow(/NEXT_PUBLIC_SITE_URL/);
+ });
+});
diff --git a/tests/setup.ts b/tests/setup.ts
new file mode 100644
index 0000000..c3237ee
--- /dev/null
+++ b/tests/setup.ts
@@ -0,0 +1,20 @@
+import { beforeEach, vi } from "vitest";
+
+// Date formatting in lib/github.ts uses the process timezone; pin it so the
+// expected strings in the tests are the same on every machine and in CI.
+process.env.TZ = "UTC";
+
+// `cacheLife` / `cacheTag` only work inside the Next.js runtime. The page and
+// data modules call them at the top of "use cache" functions, so stub them out.
+vi.mock("next/cache", () => ({
+ cacheLife: () => undefined,
+ cacheTag: () => undefined,
+}));
+
+beforeEach(() => {
+ // Tests never talk to GitHub. A token is stubbed so the authenticated code
+ // paths run; the fetch router in tests/helpers decides what comes back.
+ vi.stubEnv("GITHUB_TOKEN", "test-token");
+ vi.stubEnv("GH_TOKEN", "");
+ vi.stubEnv("NEXT_PUBLIC_SITE_URL", "https://github.brandonperfetti.com");
+});
diff --git a/vitest.config.mts b/vitest.config.mts
new file mode 100644
index 0000000..74bb08b
--- /dev/null
+++ b/vitest.config.mts
@@ -0,0 +1,20 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+
+const projectRoot = fileURLToPath(new URL(".", import.meta.url));
+
+export default defineConfig({
+ resolve: {
+ alias: {
+ "@": projectRoot,
+ },
+ },
+ test: {
+ environment: "node",
+ include: ["tests/**/*.test.{ts,tsx}"],
+ setupFiles: ["tests/setup.ts"],
+ restoreMocks: true,
+ unstubEnvs: true,
+ unstubGlobals: true,
+ },
+});
| 
+
+