@stats-forge/github-stats-forge-core 0.0.2 → 0.2.0

package/src/common/retryer.ts

@@ -1,7 +1,7 @@
-import type { CardConfig } from './config.js';
-import { CardError } from './error.js';
-import type { FetcherContext, HttpResponse } from './http.js';
-import { logger } from './log.js';
+import type { CardConfig } from './config.ts';
+import { CardError } from './error.ts';
+import type { FetcherContext, HttpResponse } from './http.ts';
+import { logger } from './log.ts';
 
 /**
  * Error-detection fields the retryer inspects to detect rate-limiting and credential failures.
@@ -19,8 +19,6 @@ interface ResponseErrors {
  * The value is generated using `Math.random()` and uniformly distributed
  * across the range.
  *
- * @param max The upper bound (exclusive). Must be a positive number.
- *
  * @returns A random integer `n` such that `0 <= n < max`.
  */
 function getRandomInt(max: number): number {
@@ -44,11 +42,6 @@ type FetcherFunction<TData = unknown, TVariables = Record<string, unknown>> = (
 /**
  * Try to execute the fetcher function until it succeeds or the max number of retries is reached.
  *
- * @template TData Shape of `response.data` returned by the fetcher.
- * @template TVariables Variables the fetcher accepts.
- * @param fetcher The fetcher function.
- * @param variables Object with arguments to pass to the fetcher function.
- * @param config Deployment config supplying the PAT pool and the transport.
  * @returns The response from the fetcher function.
  */
 const retryer = async <TData = unknown, TVariables = Record<string, unknown>>(
@@ -58,12 +51,12 @@ const retryer = async <TData = unknown, TVariables = Record<string, unknown>>(
 ): Promise<FetcherResponse<TData>> => {
   const PATs = config.pats;
 
-  if (!PATs.length) {
+  if (PATs.length === 0) {
     throw new CardError('No GitHub API tokens found', { code: 'no_tokens' });
   }
   const startPAT = getRandomInt(PATs.length);
 
-  for (let retries = 0; retries < PATs.length; retries++) {
+  for (let retries = 0; retries < PATs.length; retries += 1) {
     const currentPAT = PATs[(startPAT + retries) % PATs.length];
     if (!currentPAT) {
       continue;
@@ -77,7 +70,7 @@ const retryer = async <TData = unknown, TVariables = Record<string, unknown>>(
 
     // react on both type and message-based rate-limit signals.
     // https://github.com/anuraghazra/github-readme-stats/issues/4425
-    const errors = response.data.errors;
+    const { errors } = response.data;
     const errorType = errors?.[0]?.type;
     const errorMsg = errors?.[0]?.message ?? '';
     const isRateLimited =
@@ -89,7 +82,7 @@ const retryer = async <TData = unknown, TVariables = Record<string, unknown>>(
     }
 
     // also checking for bad credentials if any tokens gets invalidated
-    const message = response.data.message;
+    const { message } = response.data;
     const isBadCredential = message === 'Bad credentials';
     const isAccountSuspended = message === 'Sorry. Your account was suspended.';
 

package/src/fetchers/contributed-to.ts

@@ -0,0 +1,271 @@
+import type { CardConfig } from '../common/config.ts';
+import type { GitHubDateRange } from '../common/date.ts';
+import { toContributionRanges, toRange } from '../common/date.ts';
+import { CardError, USER_NOT_FOUND } from '../common/error.ts';
+import { createGraphQLFetcher } from '../common/http.ts';
+import { logger } from '../common/log.ts';
+import { chunkArray, clampValue } from '../common/ops.ts';
+import { retryer } from '../common/retryer.ts';
+import { UserContributionYearsDocument } from '../graphql/generated/contributed-to.ts';
+import {
+  MAX_REPOSITORIES_LIMIT,
+  buildReposContributedToDocument,
+} from '../graphql/reposContributedToDocument.ts';
+
+import { graphqlError } from './graphql-error.ts';
+import type { ContributedToData, ContributedRepo } from './types.ts';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Ranges per request.
+ * Each costs roughly `4 * MAX_REPOSITORIES_LIMIT` nodes,
+ * so an unchunked round of a heavily split account would breach GitHub's 500k node ceiling
+ * and lose the ranges that had already resolved along with it.
+ */
+const MAX_RANGES_PER_REQUEST = 100;
+
+const REPOS_CONTRIBUTED_TO_ERROR =
+  'Something went wrong while trying to retrieve the repository contributions data using the GraphQL API.';
+
+/** Rows the card ranks when the query names no count, and the most it will rank. */
+const DEFAULT_REPOS_COUNT = 5;
+const MAX_REPOS_COUNT = 20;
+
+const CONTRIBUTION_YEARS_ERROR =
+  'Something went wrong while trying to retrieve the contribution years using the GraphQL API.';
+
+/** What one repository accumulated over the walk. */
+interface RepoContributions {
+  /**
+   * Commit-days plus issues and pull requests opened.
+   * `CreatedCommitContribution` is one node per repository per day,
+   * so its `totalCount` counts days with commits, not commits —
+   * true commit counts would mean fetching the connection's nodes.
+   */
+  contributions: number;
+  /** Every year the user contributed to it. */
+  years: Set<number>;
+}
+
+const yearsFetcher = createGraphQLFetcher(UserContributionYearsDocument, 'bearer');
+
+/**
+ * The repositories a user contributed to across every contribution year, with what each one got.
+ *
+ * `repositoriesContributedTo` spans at most one year,
+ * so every range is fetched as an aliased `contributionsCollection(from, to)` in one request and the repos merged.
+ * A range returning `MAX_REPOSITORIES_LIMIT` results may have more,
+ * so it is halved and requeried in the next round — a split stays inside its own calendar year,
+ * which is what makes `range.from`'s year the contribution's year.
+ *
+ * Whether private contributions are included depends on the used PAT.
+ *
+ * @returns Every repository found, keyed by `nameWithOwner`.
+ */
+const fetchReposContributedTo = async (
+  /** `nameWithOwner` uses GitHub's casing, which the query-string username need not match */
+  canonicalUsername: string,
+  /** One per calendar year, so a contribution's year is the one its range starts in. */
+  ranges: Array<GitHubDateRange>,
+  includeOwnRepos: boolean,
+  config: CardConfig,
+): Promise<Map<string, RepoContributions>> => {
+  const repos = new Map<string, RepoContributions>();
+  let pending = ranges;
+
+  while (pending.length > 0) {
+    const nextPending: Array<GitHubDateRange> = [];
+
+    for (const chunk of chunkArray(pending, MAX_RANGES_PER_REQUEST)) {
+      const chunkFetcher = createGraphQLFetcher(
+        buildReposContributedToDocument(chunk, includeOwnRepos),
+        'bearer',
+      );
+      const res = await retryer(
+        chunkFetcher,
+        { login: canonicalUsername, maxRepositories: MAX_REPOSITORIES_LIMIT },
+        config,
+      );
+      if (res.data.errors) {
+        throw graphqlError(res.data.errors, res.statusText, REPOS_CONTRIBUTED_TO_ERROR);
+      }
+      const { user } = res.data.data;
+      if (!user) {
+        throw new CardError(REPOS_CONTRIBUTED_TO_ERROR, { code: 'upstream' });
+      }
+
+      for (const [index, range] of chunk.entries()) {
+        const rangeResponse = user[`range_${index}`];
+        if (!rangeResponse) {
+          throw new CardError(REPOS_CONTRIBUTED_TO_ERROR, {
+            code: 'upstream',
+          });
+        }
+
+        const counted = [
+          rangeResponse.commitContributionsByRepository,
+          rangeResponse.issueContributionsByRepository,
+          rangeResponse.pullRequestContributionsByRepository,
+        ];
+        // creating a repository is one contribution, and the field carries no count of its own
+        const created = (rangeResponse.repositoryContributions?.nodes ?? [])
+          .filter((node) => node !== null)
+          .map((node) => ({ repository: node.repository, contributions: { totalCount: 1 } }));
+        const lists = [...counted, created];
+        const isSaturated = lists.some((list) => list.length >= MAX_REPOSITORIES_LIMIT);
+
+        const rangeDays = Math.round((range.to.getTime() - range.from.getTime()) / MS_PER_DAY);
+        // a range of 1 day or less can't be split any further
+        if (isSaturated && rangeDays >= 2) {
+          // every `from` sits on UTC midnight, so the split lands on a day boundary too
+          const mid = new Date(range.from.getTime() + Math.floor(rangeDays / 2) * MS_PER_DAY);
+          // GitHub only reads the date portion,
+          // so the first half ends 1 second before `mid` to keep the halves from sharing a day
+          nextPending.push(
+            { from: range.from, to: new Date(mid.getTime() - 1000) },
+            { from: mid, to: range.to },
+          );
+          continue;
+        }
+        if (isSaturated) {
+          logger.log(
+            `Range ${range.from.toISOString()} - ${range.to.toISOString()} is saturated but cannot be split further.`,
+          );
+        }
+
+        const year = range.from.getUTCFullYear();
+        for (const { repository, contributions } of lists.flat()) {
+          const name = repository.nameWithOwner;
+          if (!includeOwnRepos && name.startsWith(`${canonicalUsername}/`)) {
+            continue;
+          }
+          const existing = repos.get(name);
+          if (existing) {
+            existing.contributions += contributions.totalCount;
+            existing.years.add(year);
+          } else {
+            repos.set(name, {
+              contributions: contributions.totalCount,
+              years: new Set([year]),
+            });
+          }
+        }
+      }
+    }
+
+    // each saturated range pushes both of its halves
+    const saturatedCount = nextPending.length / 2;
+    if (saturatedCount > 0) {
+      logger.log(`found ${saturatedCount} saturated ranges, splitting and retrying...`);
+    }
+    pending = nextPending;
+  }
+
+  return repos;
+};
+
+/**
+ * Whether a repository was excluded by the query or by the deployment.
+ *
+ * An entry matches either the full `owner/name` or the bare `name`,
+ * so a host's `EXCLUDE_REPO` — which the other cards match against bare names — still bites here,
+ * where a repository is identified by its owner as well.
+ *
+ * @returns The test, over lowercased entries.
+ */
+const excludes = (entries: Array<string>): ((nameWithOwner: string) => boolean) => {
+  const excluded = new Set(entries.map((entry) => entry.toLowerCase()));
+  return (nameWithOwner) => {
+    const lowered = nameWithOwner.toLowerCase();
+    return excluded.has(lowered) || excluded.has(lowered.slice(lowered.indexOf('/') + 1));
+  };
+};
+
+/**
+ * Rank the repositories a user has contributed to, most contributions first.
+ *
+ * `from` and `to` narrow the walk to the range they name,
+ * so the ranking, the totals and the year marks all cover that range and nothing else.
+ * A range the account contributed in no year of draws an empty card rather than an error.
+ *
+ * Ties keep the walk's order, which is chronological:
+ * the repository first seen in the earliest range comes first.
+ *
+ * An excluded repository is dropped before the total is counted,
+ * so the footer's "top n of m" never counts one the card was told not to show.
+ *
+ * @returns The ranked slice, and the totals it was taken from.
+ */
+const fetchContributedTo = async (
+  {
+    username,
+    include_own_repos = false,
+    repos_count,
+    exclude_repo = [],
+    from,
+    to,
+  }: {
+    username: string | undefined;
+    include_own_repos?: boolean | undefined;
+    /** Rows to rank; out of range or unparsed, the default stands. */
+    repos_count?: number | undefined;
+    /** Each entry is an `owner/name` or a bare `name`. */
+    exclude_repo?: Array<string>;
+    /** Start of the range to walk; as early as GitHub goes when absent. */
+    from?: Date | undefined;
+    /** End of that range. */
+    to?: Date | undefined;
+  },
+  config: CardConfig,
+): Promise<ContributedToData> => {
+  if (!username) {
+    throw CardError.missingParam(['username']);
+  }
+
+  const count =
+    repos_count !== undefined && Number.isFinite(repos_count)
+      ? clampValue(repos_count, 1, MAX_REPOS_COUNT)
+      : DEFAULT_REPOS_COUNT;
+
+  const res = await retryer(yearsFetcher, { login: username }, config);
+  if (res.data.errors) {
+    throw graphqlError(res.data.errors, res.statusText, CONTRIBUTION_YEARS_ERROR);
+  }
+
+  const { user } = res.data.data;
+  if (!user) {
+    throw new CardError('Could not fetch user.', {
+      code: 'not_found',
+      secondaryMessage: USER_NOT_FOUND,
+    });
+  }
+
+  const ranges = toContributionRanges(
+    user.contributionsCollection.contributionYears,
+    toRange(from, to),
+  );
+  const years = ranges.map((range) => range.from.getUTCFullYear());
+
+  const found = await fetchReposContributedTo(user.login, ranges, include_own_repos, config);
+
+  const isExcluded = excludes([...exclude_repo, ...config.excludeRepositories]);
+  const kept = [...found].filter(([nameWithOwner]) => !isExcluded(nameWithOwner));
+
+  const ranked: Array<ContributedRepo> = kept
+    .map(([nameWithOwner, { contributions, years: repoYears }]) => ({
+      nameWithOwner,
+      contributions,
+      years: [...repoYears].toSorted((a, b) => a - b),
+    }))
+    .toSorted((a, b) => b.contributions - a.contributions);
+
+  return {
+    login: user.login,
+    repos: ranked.slice(0, count),
+    totalRepos: kept.length,
+    years,
+  };
+};
+
+export { fetchContributedTo, fetchReposContributedTo };

package/src/fetchers/gist.ts

@@ -1,18 +1,17 @@
-import type { CardConfig } from '../common/config.js';
-import { CardError, GIST_NOT_FOUND } from '../common/error.js';
-import { createGraphQLFetcher } from '../common/http.js';
-import { retryer } from '../common/retryer.js';
-import { GistInfoDocument } from '../graphql/generated/gist.js';
-import type { GistFileInfoFragment } from '../graphql/generated/gist.js';
+import type { CardConfig } from '../common/config.ts';
+import { CardError, GIST_NOT_FOUND } from '../common/error.ts';
+import { createGraphQLFetcher } from '../common/http.ts';
+import { retryer } from '../common/retryer.ts';
+import { GistInfoDocument } from '../graphql/generated/gist.ts';
+import type { GistFileInfoFragment } from '../graphql/generated/gist.ts';
 
-import type { GistData } from './types.js';
+import type { GistData } from './types.ts';
 
 const fetcher = createGraphQLFetcher(GistInfoDocument, 'token');
 
 /**
  * This function calculates the primary language of a gist by files size.
  *
- * @param files Files.
  * @returns Primary language, or `null` when no file has a language.
  */
 const calculatePrimaryLanguage = (files: Array<GistFileInfoFragment>): string | null => {
@@ -39,9 +38,6 @@ const calculatePrimaryLanguage = (files: Array<GistFileInfoFragment>): string |
 /**
  * Fetch GitHub gist information by given username and ID.
  *
- * @param props Fetcher props.
- * @param props.id GitHub gist ID.
- * @param config Deployment config supplying the PAT pool.
  * @returns Gist data.
  */
 const fetchGist = async (
@@ -57,7 +53,7 @@ const fetchGist = async (
       code: 'upstream',
     });
   }
-  const gist = res.data.data.viewer.gist;
+  const { gist } = res.data.data.viewer;
   if (!gist) {
     throw new CardError('Gist not found', {
       code: 'not_found',

package/src/fetchers/graphql-error.ts

@@ -0,0 +1,36 @@
+import { CardError, USER_NOT_FOUND } from '../common/error.ts';
+import type { GraphQLResponse } from '../common/http.ts';
+import { logger } from '../common/log.ts';
+import { wrapTextMultiline } from '../common/render.ts';
+
+/**
+ * Turn the GraphQL `errors` a user query answered with into the error to throw.
+ *
+ * Its own module because the fetchers classify with it, and two of them may not import each other:
+ * `stats.ts` reads the repository walk out of `contributed-to.ts`.
+ *
+ * @returns `not_found` when the user does not resolve; otherwise `upstream`, worded from the first entry or from `fallback`.
+ */
+const graphqlError = (
+  errors: NonNullable<GraphQLResponse<unknown>['data']['errors']>,
+  statusText: string,
+  fallback: string,
+): CardError => {
+  logger.error(errors);
+  const [firstError] = errors;
+  if (firstError?.type === 'NOT_FOUND') {
+    return new CardError(firstError.message || 'Could not fetch user.', {
+      code: 'not_found',
+      secondaryMessage: USER_NOT_FOUND,
+    });
+  }
+  const message = firstError?.message;
+  return message
+    ? new CardError(wrapTextMultiline(message, 525, 12)[0] ?? '', {
+        code: 'upstream',
+        secondaryMessage: statusText,
+      })
+    : new CardError(fallback, { code: 'upstream' });
+};
+
+export { graphqlError };

package/src/fetchers/index.ts

@@ -1,10 +1,13 @@
-export { fetchGist } from './gist.js';
-export { fetchRepo } from './repo.js';
-export { fetchRepoUserStats, fetchStats } from './stats.js';
-export { fetchTopLanguages } from './top-languages.js';
-export { fetchWakatimeStats } from './wakatime.js';
+export { fetchContributedTo } from './contributed-to.ts';
+export { fetchGist } from './gist.ts';
+export { fetchRepo } from './repo.ts';
+export { fetchRepoUserStats, fetchStats } from './stats.ts';
+export { fetchTopLanguages } from './top-languages.ts';
+export { fetchWakatimeStats } from './wakatime.ts';
 
 export type {
+  ContributedRepo,
+  ContributedToData,
   GistData,
   Lang,
   RepoUserStats,
@@ -13,13 +16,13 @@ export type {
   TopLangData,
   WakaTimeData,
   WakaTimeLang,
-} from './types.js';
+} from './types.ts';
 
 // every fetcher takes a config, so this entry carries it rather than sending a
 // consumer back to the package root for it.
-export { CardConfig } from '../common/config.js';
-export type { CardConfigInit, PersonalAccessToken } from '../common/config.js';
-export type { FetchLike } from '../common/http.js';
-export { retryer } from '../common/retryer.js';
-export { CardError } from '../common/error.js';
-export type { ErrorCode } from '../common/error.js';
+export { CardConfig } from '../common/config.ts';
+export type { CardConfigInit, PersonalAccessToken } from '../common/config.ts';
+export type { FetchLike } from '../common/http.ts';
+export { retryer } from '../common/retryer.ts';
+export { CardError } from '../common/error.ts';
+export type { ErrorCode } from '../common/error.ts';

package/src/fetchers/repo.ts

@@ -1,11 +1,11 @@
-import type { CardConfig } from '../common/config.js';
-import { CardError, REPO_NOT_FOUND } from '../common/error.js';
-import { createGraphQLFetcher } from '../common/http.js';
-import { retryer } from '../common/retryer.js';
-import { GetRepoDocument } from '../graphql/generated/repo.js';
+import type { CardConfig } from '../common/config.ts';
+import { CardError, REPO_NOT_FOUND } from '../common/error.ts';
+import { createGraphQLFetcher } from '../common/http.ts';
+import { retryer } from '../common/retryer.ts';
+import { GetRepoDocument } from '../graphql/generated/repo.ts';
 
-import { fetchRepoUserStats } from './stats.js';
-import type { RepositoryData } from './types.js';
+import { fetchRepoUserStats } from './stats.ts';
+import type { RepositoryData } from './types.ts';
 
 const fetcher = createGraphQLFetcher(GetRepoDocument, 'token');
 
@@ -14,15 +14,6 @@ const urlExample = '/api/pin?username=USERNAME&repo=REPO_NAME';
 /**
  * Fetch repository data.
  *
- * @param props Fetcher props.
- * @param props.username GitHub username.
- * @param props.reponame GitHub repository name.
- * @param props.include_prs_authored Include count of PRs authored.
- * @param props.include_prs_commented Include count of PRs commented.
- * @param props.include_prs_reviewed Include count of PRs reviewed.
- * @param props.include_issues_authored Include count of issues authored.
- * @param props.include_issues_commented Include count of issues commented.
- * @param config Deployment config supplying the PAT pool.
  * @returns Repository data.
  */
 const fetchRepo = async (
@@ -45,35 +36,31 @@ const fetchRepo = async (
   },
   config: CardConfig,
 ): Promise<RepositoryData> => {
-  let owner = username;
-  if (reponame && reponame.includes('/')) {
-    const [parsedOwner, parsedRepo] = reponame.split('/');
-    owner = parsedOwner ?? '';
-    reponame = parsedRepo ?? '';
+  // `?repo=owner/name` carries the owner itself, and then it wins over `?username=`.
+  let parsedOwner = username;
+  let repo = reponame;
+  if (repo?.includes('/')) {
+    const [ownerFromRepo, nameFromRepo] = repo.split('/');
+    parsedOwner = ownerFromRepo ?? '';
+    repo = nameFromRepo ?? '';
   }
 
-  if (owner && !username) {
-    username = owner;
-  }
-  if (username && !owner) {
-    owner = username;
-  }
-  if (!username && !reponame) {
+  const login = username || parsedOwner;
+  if (!login && !repo) {
     throw CardError.missingParam(['username', 'repo'], urlExample);
   }
-  if (!username) {
+  if (!login) {
     throw CardError.missingParam(['username'], urlExample);
   }
-  if (!reponame) {
+  if (!repo) {
     throw CardError.missingParam(['repo'], urlExample);
   }
 
-  // the guards above leave `username` set, and `owner` mirrors it when `repo` carried none
-  const repoOwner = owner ?? username;
+  const repoOwner = parsedOwner || login;
 
-  const res = await retryer(fetcher, { login: repoOwner, repo: reponame }, config);
+  const res = await retryer(fetcher, { login: repoOwner, repo }, config);
 
-  const data = res.data.data;
+  const { data } = res.data;
 
   if (!data.user && !data.organization) {
     throw new CardError('Not found', {
@@ -83,7 +70,7 @@ const fetchRepo = async (
   }
 
   if (data.organization === null && data.user) {
-    const repository = data.user.repository;
+    const { repository } = data.user;
     if (!repository || repository.isPrivate) {
       throw new CardError('User Repository Not found', {
         code: 'not_found',
@@ -92,8 +79,8 @@ const fetchRepo = async (
     }
     const repoUserStats = await fetchRepoUserStats(
       {
-        username,
-        repo: [`${repoOwner}/${reponame}`],
+        username: login,
+        repo: [`${repoOwner}/${repo}`],
         include_prs_authored,
         include_prs_commented,
         include_prs_reviewed,
@@ -109,7 +96,7 @@ const fetchRepo = async (
   }
 
   if (data.user === null && data.organization) {
-    const repository = data.organization.repository;
+    const { repository } = data.organization;
     if (!repository || repository.isPrivate) {
       throw new CardError('Organization Repository Not found', {
         code: 'not_found',
@@ -118,8 +105,8 @@ const fetchRepo = async (
     }
     const repoUserStats = await fetchRepoUserStats(
       {
-        username,
-        repo: [`${repoOwner}/${reponame}`],
+        username: login,
+        repo: [`${repoOwner}/${repo}`],
         include_prs_authored,
         include_prs_commented,
         include_prs_reviewed,