feat: implement GitHub GraphQL client and refactor GitHub data fetching

- Added a new GitHubGraphQLClient to handle GraphQL requests to the GitHub API with rate limit handling and retry logic.
- Refactored GitHub data fetching logic to utilize the new GraphQL client, improving error handling and caching mechanisms.
- Removed reaction handling from score calculations, simplifying the scoring logic for issues and discussions.
- Updated scoring functions to focus on repository visibility and discussion activity without relying on reactions.
- Enhanced caching strategies for GitHub user data to improve performance and reduce API calls.

Author: O2sa

app/api/compare/route.ts

@@ -2,15 +2,18 @@ import { NextResponse } from "next/server";
 import { fetchGitHubUserData } from "../../../lib/github";
 import { calculateUserScore } from "../../../lib/score";
 import { normalizeSelectedLanguages } from "@/lib/scoring/languageScoring";
+import { toSafeApiError } from "@/lib/github-graphql-client";
+import type { CompareInsights } from "@/types/api-response";
+import {
+  DEFAULT_LOCALE,
+  LOCALE_COOKIE,
+  isSupportedLocale,
+  parseAcceptLanguage,
+  type Locale,
+} from "@/lib/i18n-core";
 
 export const runtime = "nodejs";
 
-type CompareRequestBody = {
-  username1?: string;
-  username2?: string;
-  selectedLanguages?: string[];
-};
-
 type ComparedUserResult = {
   username: string;
   name: string | null;
@@ -119,42 +122,223 @@ function calculateWinner(users: ComparedUserResult[]): {
   return result;
 }
 
+function createComparisonInsights(
+  users: ComparedUserResult[],
+  locale: Locale,
+): CompareInsights | undefined {
+  if (users.length !== 2) {
+    return undefined;
+  }
+
+  const [user1, user2] = users;
+  const user1Name = user1.name || user1.username;
+  const user2Name = user2.name || user2.username;
+
+  const finalLeader = user1.finalScore >= user2.finalScore ? user1 : user2;
+  const finalFollower = finalLeader.username === user1.username ? user2 : user1;
+  const finalDiff = Math.abs(user1.finalScore - user2.finalScore);
+
+  const repoLeader = user1.repoScore >= user2.repoScore ? user1 : user2;
+  const prLeader = user1.prScore >= user2.prScore ? user1 : user2;
+  const contributionLeader =
+    user1.contributionScore >= user2.contributionScore ? user1 : user2;
+
+  const user1Strengths: string[] = [];
+  const user2Strengths: string[] = [];
+
+  if (repoLeader.username === user1.username) {
+    user1Strengths.push(
+      locale === "ar"
+        ? "أثر أقوى في المستودعات ووضوح أعلى للمشاريع."
+        : "Stronger repository impact and project visibility.",
+    );
+  } else {
+    user2Strengths.push(
+      locale === "ar"
+        ? "أثر أقوى في المستودعات ووضوح أعلى للمشاريع."
+        : "Stronger repository impact and project visibility.",
+    );
+  }
+
+  if (prLeader.username === user1.username) {
+    user1Strengths.push(
+      locale === "ar"
+        ? "أثر أعلى من طلبات السحب الخارجية المدمجة."
+        : "Higher merged external pull request impact.",
+    );
+  } else {
+    user2Strengths.push(
+      locale === "ar"
+        ? "أثر أعلى من طلبات السحب الخارجية المدمجة."
+        : "Higher merged external pull request impact.",
+    );
+  }
+
+  if (contributionLeader.username === user1.username) {
+    user1Strengths.push(
+      locale === "ar"
+        ? "أثر أعلى من المساهمات الخارجية في المشاكل والنقاشات."
+        : "Higher external issue/discussion contribution impact.",
+    );
+  } else {
+    user2Strengths.push(
+      locale === "ar"
+        ? "أثر أعلى من المساهمات الخارجية في المشاكل والنقاشات."
+        : "Higher external issue/discussion contribution impact.",
+    );
+  }
+
+  const recommendationsForUser = (target: ComparedUserResult): string[] => {
+    const recommendations: string[] = [];
+
+    if (target.repoScore < repoLeader.repoScore) {
+      recommendations.push(
+        locale === "ar"
+          ? "التركيز على عدد أقل من المستودعات العامة عالية الجودة مع نشاط مستمر."
+          : "Invest in fewer high-quality public repositories with sustained activity.",
+      );
+    }
+    if (target.prScore < prLeader.prScore) {
+      recommendations.push(
+        locale === "ar"
+          ? "زيادة المساهمات المدمجة في مستودعات خارجية ذات وصول مجتمعي أوسع."
+          : "Increase merged contributions to external repositories with broader community reach.",
+      );
+    }
+    if (target.contributionScore < contributionLeader.contributionScore) {
+      recommendations.push(
+        locale === "ar"
+          ? "المشاركة بشكل أكبر في المشاكل والنقاشات الخارجية عالية الأثر لتحسين الحضور المجتمعي."
+          : "Participate more in high-signal external issues/discussions to improve community impact.",
+      );
+    }
+    if (recommendations.length === 0) {
+      recommendations.push(
+        locale === "ar"
+          ? "الحفاظ على الاستمرارية بين المستودعات وطلبات السحب والمشاركة المجتمعية الخارجية."
+          : "Maintain consistency across repositories, pull requests, and external community engagement.",
+      );
+    }
+
+    return recommendations;
+  };
+
+  return {
+    summary:
+      locale === "ar"
+        ? `${finalLeader.name || finalLeader.username} يتصدر حاليًا درجة الأثر المفتوح المصدر بفارق ${finalDiff} نقطة عن ${finalFollower.name || finalFollower.username}.`
+        : `${finalLeader.name || finalLeader.username} currently has the higher public open-source impact score by ${finalDiff} points over ${finalFollower.name || finalFollower.username}.`,
+    keyDifferences: [
+      locale === "ar"
+        ? `${repoLeader.name || repoLeader.username} يتصدر أثر المستودعات (${repoLeader.repoScore} مقابل ${repoLeader.username === user1.username ? user2.repoScore : user1.repoScore}).`
+        : `${repoLeader.name || repoLeader.username} leads repository impact (${repoLeader.repoScore} vs ${repoLeader.username === user1.username ? user2.repoScore : user1.repoScore}).`,
+      locale === "ar"
+        ? `${prLeader.name || prLeader.username} يتصدر أثر طلبات السحب (${prLeader.prScore} مقابل ${prLeader.username === user1.username ? user2.prScore : user1.prScore}).`
+        : `${prLeader.name || prLeader.username} leads pull request impact (${prLeader.prScore} vs ${prLeader.username === user1.username ? user2.prScore : user1.prScore}).`,
+      locale === "ar"
+        ? `${contributionLeader.name || contributionLeader.username} يتصدر أثر مساهمات المجتمع (${contributionLeader.contributionScore} مقابل ${contributionLeader.username === user1.username ? user2.contributionScore : user1.contributionScore}).`
+        : `${contributionLeader.name || contributionLeader.username} leads community contribution impact (${contributionLeader.contributionScore} vs ${contributionLeader.username === user1.username ? user2.contributionScore : user1.contributionScore}).`,
+    ],
+    user1Strengths:
+      user1Strengths.length > 0
+        ? user1Strengths
+        : [
+            locale === "ar"
+              ? "أثر عام متوازن عبر أهم أبعاد التقييم."
+              : "Balanced overall impact across major scoring dimensions.",
+          ],
+    user2Strengths:
+      user2Strengths.length > 0
+        ? user2Strengths
+        : [
+            locale === "ar"
+              ? "أثر عام متوازن عبر أهم أبعاد التقييم."
+              : "Balanced overall impact across major scoring dimensions.",
+          ],
+    recommendations: {
+      user1: recommendationsForUser(user1),
+      user2: recommendationsForUser(user2),
+    },
+    confidenceNote:
+      locale === "ar"
+        ? `هذه المقارنة حتمية ومبنية على إشارات GitHub العامة الملتقطة لكل من ${user1Name} و${user2Name}.`
+        : `This comparison is deterministic and based on public GitHub signals captured for ${user1Name} and ${user2Name}.`,
+  };
+}
+
+function resolveLocale(request: Request): Locale {
+  const cookieHeader = request.headers.get("cookie");
+  const localeFromCookie = cookieHeader
+    ?.split(";")
+    .map((value) => value.trim())
+    .find((value) => value.startsWith(`${LOCALE_COOKIE}=`))
+    ?.split("=")[1];
+
+  if (isSupportedLocale(localeFromCookie)) {
+    return localeFromCookie;
+  }
+
+  return parseAcceptLanguage(
+    request.headers.get("accept-language"),
+    ["en", "ar"],
+    DEFAULT_LOCALE,
+  );
+}
+
 async function compareUsers(
   usernames: string[],
   selectedLanguages: string[],
 ): Promise<ComparedUserResult[]> {
-  return Promise.all(
-    usernames.map(async (username) => {
-      const data = await fetchGitHubUserData(username);
-      const score = calculateUserScore(
-        {
-          ...data,
-          selectedLanguages,
-        },
-        username,
-      );
+  const results: ComparedUserResult[] = [];
 
-      return {
-        username,
-        name: data.name,
-        avatarUrl: data.avatarUrl,
-        repoScore: Math.round(score.repoScore),
-        prScore: Math.round(score.prScore),
-        contributionScore: Math.round(score.contributionScore),
-        finalScore: Math.round(score.finalScore),
-        normalizedRepoScore: Math.round(score.normalizedRepoScore),
-        normalizedPRScore: Math.round(score.normalizedPRScore),
-        normalizedContributionScore: Math.round(score.normalizedContributionScore),
-        normalizedFinalScore: Math.round(score.normalizedFinalScore),
-        topRepos: score.topRepos,
-        topPullRequests: score.topPullRequests,
-        topCommunityContributions: score.topCommunityContributions,
-        languageScores: score.languageScores,
-        signals: score.signals,
-        explanations: score.explanations,
-      };
-    }),
-  );
+  for (const username of usernames) {
+    const data = await fetchGitHubUserData(username);
+    const score = calculateUserScore(
+      {
+        ...data,
+        selectedLanguages,
+      },
+      username,
+    );
+
+    results.push({
+      username,
+      name: data.name,
+      avatarUrl: data.avatarUrl,
+      repoScore: Math.round(score.repoScore),
+      prScore: Math.round(score.prScore),
+      contributionScore: Math.round(score.contributionScore),
+      finalScore: Math.round(score.finalScore),
+      normalizedRepoScore: Math.round(score.normalizedRepoScore),
+      normalizedPRScore: Math.round(score.normalizedPRScore),
+      normalizedContributionScore: Math.round(score.normalizedContributionScore),
+      normalizedFinalScore: Math.round(score.normalizedFinalScore),
+      topRepos: score.topRepos,
+      topPullRequests: score.topPullRequests,
+      topCommunityContributions: score.topCommunityContributions,
+      languageScores: score.languageScores,
+      signals: score.signals,
+      explanations: score.explanations,
+    });
+  }
+
+  return results;
+}
+
+function toApiErrorStatus(code: ReturnType<typeof toSafeApiError>["code"]): number {
+  switch (code) {
+    case "RATE_LIMITED":
+    case "TEMPORARY_THROTTLE":
+      return 429;
+    case "GITHUB_AUTH":
+      return 401;
+    case "GITHUB_NOT_FOUND":
+      return 404;
+    case "NETWORK":
+      return 503;
+    default:
+      return 500;
+  }
 }
 
 export async function GET(request: Request) {
@@ -164,66 +348,34 @@ export async function GET(request: Request) {
     .map((username) => username.trim())
     .filter(Boolean);
 
-  if (usernames.length === 0) {
+  if (usernames.length !== 2) {
     return NextResponse.json(
-      { success: false, error: "provide at least one username param" },
+      { success: false, error: "provide exactly two username params" },
       { status: 400 },
     );
   }
 
   try {
+    const locale = resolveLocale(request);
     const selectedLanguages = parseSelectedLanguagesFromSearchParams(searchParams);
     const users = await compareUsers(usernames, selectedLanguages);
     const winnerData = calculateWinner(users);
-    return NextResponse.json({ success: true, users, ...winnerData });
+    const insights = createComparisonInsights(users, locale);
+    return NextResponse.json({ success: true, users, ...winnerData, insights });
   } catch (error: unknown) {
     console.error("GitHub score error:", error);
-    const message =
+    const safeError =
       error instanceof Error && error.message === "User not found"
-        ? "GitHub user not found"
-        : "Failed to calculate score";
-    return NextResponse.json({ success: false, error: message }, { status: 500 });
-  }
-}
-
-export async function POST(request: Request) {
-  let body: CompareRequestBody;
-
-  try {
-    body = (await request.json()) as CompareRequestBody;
-  } catch {
-    return NextResponse.json(
-      { success: false, error: "Invalid JSON body" },
-      { status: 400 },
-    );
-  }
+        ? { code: "GITHUB_NOT_FOUND" as const, message: "GitHub user not found" }
+        : toSafeApiError(error);
 
-  const usernames = [body.username1, body.username2]
-    .map((username) => username?.trim() ?? "")
-    .filter(Boolean);
-
-  if (usernames.length !== 2) {
     return NextResponse.json(
       {
         success: false,
-        error: "Provide username1 and username2 in the request body",
+        error: safeError.message,
+        errorDetails: safeError,
       },
-      { status: 400 },
+      { status: toApiErrorStatus(safeError.code) },
     );
   }
-
-  const selectedLanguages = normalizeSelectedLanguages(body.selectedLanguages);
-
-  try {
-    const users = await compareUsers(usernames, selectedLanguages);
-    const winnerData = calculateWinner(users);
-    return NextResponse.json({ success: true, users, ...winnerData });
-  } catch (error: unknown) {
-    console.error("GitHub score error:", error);
-    const message =
-      error instanceof Error && error.message === "User not found"
-        ? "GitHub user not found"
-        : "Failed to calculate score";
-    return NextResponse.json({ success: false, error: message }, { status: 500 });
-  }
 }