@stats-forge/github-stats-forge-core 0.0.1 → 0.1.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/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/index.ts

@@ -1,8 +1,8 @@
-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 { 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 {
   GistData,
@@ -13,13 +13,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,

package/src/fetchers/stats.ts

@@ -1,30 +1,29 @@
-import githubUsernameRegex from 'github-username-regex';
-
-import { calculateRank } from '../calculateRank.js';
-import type { CardConfig } from '../common/config.js';
-import type { GitHubDateRange } from '../common/date.js';
-import { getGitHubYearRange, toGitHubDateTime } from '../common/date.js';
-import { CardError, USER_NOT_FOUND } from '../common/error.js';
-import { wrapTextMultiline } from '../common/fmt.js';
-import { createGraphQLFetcher, httpRequest } from '../common/http.js';
-import type { FetcherContext, GraphQLResponse } from '../common/http.js';
-import { logger } from '../common/log.js';
-import { buildSearchFilter, chunkArray, parseOwnerAffiliations } from '../common/ops.js';
-import { retryer } from '../common/retryer.js';
-import type { FetcherResponse } from '../common/retryer.js';
-import { buildContributionsDocument } from '../graphql/contributionsDocument.js';
-import { UserInfoDocument, UserReposDocument } from '../graphql/generated/stats.js';
+import { calculateRank } from '../calculateRank.ts';
+import type { CardConfig } from '../common/config.ts';
+import { GITHUB_USERNAME_PATTERN } from '../common/constants.ts';
+import type { GitHubDateRange } from '../common/date.ts';
+import { getGitHubYearRange, toGitHubDateTime } from '../common/date.ts';
+import { CardError, USER_NOT_FOUND } from '../common/error.ts';
+import { createGraphQLFetcher, httpRequest } from '../common/http.ts';
+import type { FetcherContext, GraphQLResponse } from '../common/http.ts';
+import { logger } from '../common/log.ts';
+import { buildSearchFilter, chunkArray, parseOwnerAffiliations } from '../common/ops.ts';
+import { wrapTextMultiline } from '../common/render.ts';
+import { retryer } from '../common/retryer.ts';
+import type { FetcherResponse } from '../common/retryer.ts';
+import { buildContributionsDocument } from '../graphql/contributionsDocument.ts';
+import { UserInfoDocument, UserReposDocument } from '../graphql/generated/stats.ts';
 import type {
   RepoNodeFragment,
   UserInfoQuery,
   UserInfoQueryVariables,
-} from '../graphql/generated/stats.js';
+} from '../graphql/generated/stats.ts';
 import {
   MAX_REPOSITORIES_LIMIT,
   buildReposContributedToDocument,
-} from '../graphql/reposContributedToDocument.js';
+} from '../graphql/reposContributedToDocument.ts';
 
-import type { RepoUserStats, StatsData } from './types.js';
+import type { RepoUserStats, StatsData } from './types.ts';
 
 /** The subset of the stats response `statsFetcher` returns and threads on. */
 type StatsFetcherResponse = Pick<GraphQLResponse<UserInfoQuery>, 'data' | 'statusText'>;
@@ -36,19 +35,10 @@ const reposFetcher = createGraphQLFetcher(UserReposDocument, 'bearer');
 /**
  * Fetch stats information for a given username.
  *
- * @param variables Fetcher variables.
- * @param variables.username GitHub username.
- * @param variables.includeMergedPullRequests Include merged pull requests.
- * @param variables.includeDiscussions Include discussions.
- * @param variables.includeDiscussionsAnswers Include discussions answers.
- * @param variables.startTime Time to start the count of total commits.
- * @param variables.ownerAffiliations The owner affiliations to filter by. Default: OWNER.
- * @param variables.includeUserRepositories Whether to include the user's own repositories in the repos contributed to.
- * @param config Deployment config supplying the PAT pool.
- * @returns The stats response, with every fetched page's repos merged in.
- *
  * @description Supports multi-page fetching when the `FETCH_MULTI_PAGE_STARS`
  * env variable is `true` or a fetch limit.
+ *
+ * @returns The stats response, with every fetched page's repos merged in.
  */
 const statsFetcher = async (
   {
@@ -118,11 +108,11 @@ const statsFetcher = async (
 
     pageRepositories = page.data.data.user?.repositories;
     extraRepoNodes.push(...(pageRepositories?.nodes ?? []));
-    fetchedPages++;
+    fetchedPages += 1;
   }
 
   if (extraRepoNodes.length > 0) {
-    // deep copy to avoid mutating the response cached by the frontend
+    // defensive: the merge below is the only place a parsed response is mutated
     stats = structuredClone({
       data: stats.data,
       statusText: stats.statusText,
@@ -136,13 +126,9 @@ const statsFetcher = async (
 /**
  * Fetch total items count using the REST search API.
  *
- * @param variables Fetcher variables.
- * @param token GitHub token.
- * @param context What the retryer supplies each attempt.
- * @param context.fetch Transport to send the request with.
- * @returns The search response, carrying `total_count`.
- *
  * @see https://developer.github.com/v3/search/#search-commits
+ *
+ * @returns The search response, carrying `total_count`.
  */
 const fetchTotalItems = (
   variables: Record<string, unknown>,
@@ -155,9 +141,10 @@ const fetchTotalItems = (
   const owner = variables['owner'] as Array<string> | string;
   return httpRequest(
     fetch,
-    `https://api.github.com/search/${type}?per_page=1&q=` +
-      buildSearchFilter(repo, owner).replaceAll(' ', '+') +
-      filter,
+    `https://api.github.com/search/${type}?per_page=1&q=${buildSearchFilter(repo, owner).replaceAll(
+      ' ',
+      '+',
+    )}${filter}`,
     {
       method: 'GET',
       headers: {
@@ -172,18 +159,11 @@ const fetchTotalItems = (
 /**
  * Fetch a total count for a given username via the REST search API.
  *
- * @param props Fetcher props.
- * @param props.username GitHub username.
- * @param props.repo Repositories the search is scoped to.
- * @param props.owner Owners the search is scoped to.
- * @param props.type Search endpoint to hit, `issues` or `commits`.
- * @param props.filter Query fragment appended to the scope filter.
- * @param config Deployment config supplying the PAT pool.
- * @returns Total count.
- *
  * The GraphQL API can't return this.
  * @see https://github.com/anuraghazra/github-readme-stats/issues/92#issuecomment-661026467
  * @see https://github.com/anuraghazra/github-readme-stats/pull/211
+ *
+ * @returns Total count.
  */
 const totalItemsFetcher = async (
   {
@@ -201,7 +181,7 @@ const totalItemsFetcher = async (
   },
   config: CardConfig,
 ): Promise<number> => {
-  if (!githubUsernameRegex.test(username)) {
+  if (!GITHUB_USERNAME_PATTERN.test(username)) {
     logger.log('Invalid username provided.');
     throw new CardError('Invalid username provided.', {
       code: 'invalid_param',
@@ -216,14 +196,14 @@ const totalItemsFetcher = async (
       { login: username, repo, owner, type, filter },
       config,
     );
-  } catch (err) {
-    logger.log(err);
-    throw err;
+  } catch (error) {
+    logger.log(error);
+    throw error;
   }
 
   const totalCount = res.data.total_count;
-  if (totalCount === undefined || isNaN(totalCount)) {
-    logger.error('GitHub error: ' + JSON.stringify(res.data));
+  if (typeof totalCount !== 'number' || Number.isNaN(totalCount)) {
+    logger.error(`GitHub error: ${JSON.stringify(res.data)}`);
     throw new CardError('Could not fetch data from GitHub REST API.', {
       code: 'upstream',
     });
@@ -234,16 +214,6 @@ const totalItemsFetcher = async (
 /**
  * Fetch the per-repository counts the REST search API answers, one request each.
  *
- * @param props Fetcher props.
- * @param props.username GitHub username.
- * @param props.repo Repositories the search is scoped to.
- * @param props.owner Owners the search is scoped to.
- * @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 Only the counts that were asked for.
  */
 const fetchRepoUserStats = async (
@@ -334,10 +304,6 @@ const fetchRepoUserStats = async (
 
 /**
  * Turn a GraphQL `errors` payload into the error to throw.
- *
- * @param errors Errors from the response envelope.
- * @param statusText HTTP status text, used as the error type when GitHub gave a message.
- * @param fallback Message when GitHub gave none.
  */
 const graphqlError = (
   errors: NonNullable<GraphQLResponse<unknown>['data']['errors']>,
@@ -382,7 +348,7 @@ const fetchTotalContributions = async (
     );
   }
 
-  const user = contribRes.data.data.user;
+  const { user } = contribRes.data.data;
   if (!user) {
     return 0;
   }
@@ -420,39 +386,35 @@ const REPOS_CONTRIBUTED_TO_ERROR =
  *
  * Whether private contributions are included depends on the used PAT.
  *
- * @param canonicalUsername Username as GitHub reports it; `nameWithOwner` uses its
- *        casing, which the raw query-string username need not match.
- * @param years Contribution years to walk.
- * @param includeOwnRepos Whether to count the user's own repositories.
- * @param config Deployment config supplying the PAT pool.
  * @returns Count of repositories.
  */
 const fetchAllTimeReposContributedTo = async (
+  /** `nameWithOwner` uses GitHub's casing, which the query-string username need not match */
   canonicalUsername: string,
   years: Array<number>,
   includeOwnRepos: boolean,
   config: CardConfig,
 ): Promise<number> => {
   const repos = new Set<string>();
-  let pending = years.map(getGitHubYearRange);
+  let pending = years.map((year) => getGitHubYearRange(year));
 
   while (pending.length > 0) {
     const nextPending: Array<GitHubDateRange> = [];
 
     for (const chunk of chunkArray(pending, MAX_RANGES_PER_REQUEST)) {
-      const fetcher = createGraphQLFetcher(
+      const chunkFetcher = createGraphQLFetcher(
         buildReposContributedToDocument(chunk, includeOwnRepos),
         'bearer',
       );
       const res = await retryer(
-        fetcher,
+        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.user;
+      const { user } = res.data.data;
       if (!user) {
         throw new CardError(REPOS_CONTRIBUTED_TO_ERROR, { code: 'upstream' });
       }
@@ -515,26 +477,6 @@ const fetchAllTimeReposContributedTo = async (
 /**
  * Fetch stats for a given username.
  *
- * @param props Fetcher props.
- * @param props.username GitHub username.
- * @param props.include_all_commits Include all commits.
- * @param props.exclude_repo Repositories to exclude.
- * @param props.include_merged_pull_requests Include merged pull requests.
- * @param props.include_discussions Include discussions.
- * @param props.include_discussions_answers Include discussions answers.
- * @param props.commits_year Year to count total commits.
- * @param props.repo Repositories to scope the REST search to.
- * @param props.owner Owners to scope the REST search to.
- * @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 props.ownerAffiliations Owner affiliations. Default: OWNER.
- * @param props.include_contributions Include all-time contributions.
- * @param props.include_all_time_contribs Include all-time count of repos contributed to.
- * @param props.contribs_include_own_repos Include user-owned repos in contributed-to counts.
- * @param config Deployment config supplying the PAT pool.
  * @returns Stats data.
  */
 const fetchStats = async (
@@ -625,7 +567,7 @@ const fetchStats = async (
   // Catch GraphQL errors.
   if (res.data.errors) {
     logger.error(res.data.errors);
-    const firstError = res.data.errors[0];
+    const [firstError] = res.data.errors;
     if (firstError?.type === 'NOT_FOUND') {
       throw new CardError(firstError.message || 'Could not fetch user.', {
         code: 'not_found',
@@ -644,7 +586,7 @@ const fetchStats = async (
     );
   }
 
-  const user = res.data.data.user;
+  const { user } = res.data.data;
   if (!user) {
     throw new CardError('Could not fetch user.', {
       code: 'not_found',