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

package/src/fetchers/top-languages.ts

@@ -1,30 +1,22 @@
-import type { CardConfig } from '../common/config.js';
-import { CardError, USER_NOT_FOUND } from '../common/error.js';
-import { wrapTextMultiline } from '../common/fmt.js';
-import { createGraphQLFetcher } from '../common/http.js';
-import { logger } from '../common/log.js';
-import { parseOwnerAffiliations } from '../common/ops.js';
-import { retryer } from '../common/retryer.js';
-import { TopLanguagesDocument } from '../graphql/generated/top-languages.js';
+import type { CardConfig } from '../common/config.ts';
+import { CardError } from '../common/error.ts';
+import { createGraphQLFetcher } from '../common/http.ts';
+import { parseOwnerAffiliations } from '../common/ops.ts';
+import { retryer } from '../common/retryer.ts';
+import { TopLanguagesDocument } from '../graphql/generated/top-languages.ts';
 import type {
   TopLanguageFragment,
   TopLanguagesRepositoryFragment,
-} from '../graphql/generated/top-languages.js';
+} from '../graphql/generated/top-languages.ts';
 
-import type { Lang, TopLangData } from './types.js';
+import { graphqlError } from './graphql-error.ts';
+import type { Lang, TopLangData } from './types.ts';
 
 const fetcher = createGraphQLFetcher(TopLanguagesDocument, 'token');
 
 /**
  * Fetch top languages for a given username.
  *
- * @param props Fetcher props.
- * @param props.username GitHub username.
- * @param props.exclude_repo List of repositories to exclude. Default: [].
- * @param props.size_weight Weightage to be given to size.
- * @param props.count_weight Weightage to be given to count.
- * @param props.ownerAffiliations The owner affiliations to filter by. Default: OWNER.
- * @param config Deployment config supplying the PAT pool.
  * @returns Top languages data.
  */
 const fetchTopLanguages = async (
@@ -58,23 +50,10 @@ const fetchTopLanguages = async (
   );
 
   if (res.data.errors) {
-    logger.error(res.data.errors);
-    const firstError = res.data.errors[0];
-    if (firstError?.type === 'NOT_FOUND') {
-      throw new CardError(firstError.message || 'Could not fetch user.', {
-        code: 'not_found',
-        secondaryMessage: USER_NOT_FOUND,
-      });
-    }
-    if (firstError?.message) {
-      throw new CardError(wrapTextMultiline(firstError.message, 525, 12)[0] ?? '', {
-        code: 'upstream',
-        secondaryMessage: res.statusText,
-      });
-    }
-    throw new CardError(
+    throw graphqlError(
+      res.data.errors,
+      res.statusText,
       'Something went wrong while trying to retrieve the language data using the GraphQL API.',
-      { code: 'upstream' },
     );
   }
 
@@ -82,53 +61,46 @@ const fetchTopLanguages = async (
   const allExcludedRepos = [...exclude_repo, ...config.excludeRepositories];
 
   // populate repoToHide map for quick lookup while filtering out
-  allExcludedRepos.forEach((repoName) => {
+  for (const repoName of allExcludedRepos) {
     repoToHide[repoName] = true;
-  });
+  }
 
   // filter out repositories to be hidden
   const repoNodes = (res.data.data.user?.repositories.nodes ?? []).filter(
     (node): node is TopLanguagesRepositoryFragment => !!node && !repoToHide[node.name],
   );
 
-  // flatten edges across repos. Order matters: `concat(acc)` prepends, and the
-  // shared repoCount below depends on visitation order.
-  const languageEdges = repoNodes.reduce<Array<TopLanguageFragment>>((acc, repo) => {
+  let languageEdges: Array<TopLanguageFragment> = [];
+  for (const repo of repoNodes) {
     const edges = (repo.languages?.edges ?? []).filter(
       (edge): edge is TopLanguageFragment => !!edge,
     );
-    return edges.length > 0 ? edges.concat(acc) : acc;
-  }, []);
+    if (edges.length > 0) {
+      languageEdges = [...edges, ...languageEdges];
+    }
+  }
 
-  // accumulate size and repo count per language
+  // accumulate size and repo count per language, each read back off the language's own entry
   const languageMap: Record<string, Lang> = {};
-  let repoCount = 0;
   for (const edge of languageEdges) {
     const existing = languageMap[edge.node.name];
-
-    // same language seen again: add to its size and bump count; else reset to 1
-    let langSize = edge.size;
-    if (existing && edge.node.name === existing.name) {
-      langSize = edge.size + existing.size;
-      repoCount += 1;
-    } else {
-      repoCount = 1;
-    }
     languageMap[edge.node.name] = {
       name: edge.node.name,
       color: edge.node.color,
-      size: langSize,
-      count: repoCount,
+      size: edge.size + (existing?.size ?? 0),
+      count: (existing?.count ?? 0) + 1,
     };
   }
 
   // comparison index calculation
   for (const lang of Object.values(languageMap)) {
-    lang.size = Math.pow(lang.size, size_weight) * Math.pow(lang.count, count_weight);
+    lang.size = lang.size ** size_weight * lang.count ** count_weight;
   }
 
   // return languages sorted by (weighted) size, descending
-  return Object.fromEntries(Object.entries(languageMap).sort(([, a], [, b]) => b.size - a.size));
+  return Object.fromEntries(
+    Object.entries(languageMap).toSorted(([, a], [, b]) => b.size - a.size),
+  );
 };
 
 export { fetchTopLanguages };

package/src/fetchers/types.ts

@@ -1,4 +1,5 @@
-import type { RepoInfoFragment } from '../graphql/generated/repo.js';
+import type { GitHubDateRange } from '../common/date.ts';
+import type { RepoInfoFragment } from '../graphql/generated/repo.ts';
 
 export interface GistData {
   name: string;
@@ -39,6 +40,8 @@ export interface StatsData {
   mergedPRsPercentage: number;
   totalReviews: number;
   totalCommits: number;
+  /** The range `totalCommits` covers; `undefined` when it is GitHub's own last year, or all time. */
+  commitsRange: GitHubDateRange | undefined;
   totalIssues: number;
   totalStars: number;
   totalDiscussionsStarted: number;
@@ -54,6 +57,29 @@ export interface StatsData {
   rank: { level: string; percentile: number };
 }
 
+/** One repository a user contributed to, as the card ranks it. */
+export interface ContributedRepo {
+  nameWithOwner: string;
+  /**
+   * Commit-days plus issues and pull requests opened, summed over every year.
+   * Not a commit count: GitHub groups commit contributions by day, not by commit.
+   */
+  contributions: number;
+  /** Every year the user contributed to it, ascending. */
+  years: Array<number>;
+}
+
+export interface ContributedToData {
+  /** GitHub's own casing of the login, which the query param need not match. */
+  login: string;
+  /** The ranked slice, most contributions first. */
+  repos: Array<ContributedRepo>;
+  /** Every repository the walk found, which `repos` is a slice of. */
+  totalRepos: number;
+  /** The account's contribution years, ascending — the range the year marks cover. */
+  years: Array<number>;
+}
+
 export interface Lang {
   name: string;
   // GitHub's GraphQL `Language.color` is nullable — the card falls back to a default.

package/src/fetchers/wakatime.ts

@@ -1,18 +1,14 @@
-import type { CardConfig } from '../common/config.js';
-import { CardError, WAKATIME_USER_NOT_FOUND } from '../common/error.js';
-import { httpRequest } from '../common/http.js';
+import type { CardConfig } from '../common/config.ts';
+import { CardError, WAKATIME_USER_NOT_FOUND } from '../common/error.ts';
+import { httpRequest } from '../common/http.ts';
 
-import type { WakaTimeData } from './types.js';
+import type { WakaTimeData } from './types.ts';
 
 /**
  * WakaTime data fetcher.
  *
  * WakaTime needs no GitHub token; the config is here for the transport it carries.
  *
- * @param props Fetcher props.
- * @param props.username WakaTime username.
- * @param props.api_domain Optional WakaTime API domain (defaults to `wakatime.com`).
- * @param config Deployment config supplying the transport.
  * @returns WakaTime data response.
  */
 const fetchWakatimeStats = async (
@@ -29,7 +25,7 @@ const fetchWakatimeStats = async (
     throw CardError.missingParam(['username']);
   }
 
-  const domain = api_domain ? api_domain.replace(/\/$/gi, '') : 'wakatime.com';
+  const domain = api_domain ? api_domain.replaceAll(/\/$/gi, '') : 'wakatime.com';
   const res = await httpRequest<{ data: WakaTimeData }>(
     config.fetch,
     `https://${domain}/api/v1/users/${username}/stats?is_including_today=true`,

package/src/graphql/contributionsCollection.ts

@@ -0,0 +1,18 @@
+import type { GitHubDateRange } from '../common/date.ts';
+import { toGitHubDateTime } from '../common/date.ts';
+
+/** Naming `to` is not optional: GitHub defaults an omitted one to a year after `from`. */
+const contributionsCollectionOf = ({ from, to }: GitHubDateRange): string =>
+  `contributionsCollection(from: "${toGitHubDateTime(from)}", to: "${toGitHubDateTime(to)}")`;
+
+/**
+ * One `contributionsCollection` field per range, aliased by position.
+ *
+ * @returns The fields, for a query that selects `fragment`.
+ */
+const aliasedRanges = (ranges: Array<GitHubDateRange>, fragment: string): string =>
+  ranges
+    .map((range, index) => `range_${index}: ${contributionsCollectionOf(range)} { ...${fragment} }`)
+    .join('\n');
+
+export { aliasedRanges };

package/src/graphql/contributionsDocument.ts

@@ -1,44 +1,39 @@
-import { getGitHubYearRange, toGitHubDateTime } from '../common/date.js';
+import type { GitHubDateRange } from '../common/date.ts';
 
-import type { YearContributionsFragment } from './generated/stats.js';
-import { graphqlDocument } from './graphqlDocument.js';
+import { aliasedRanges } from './contributionsCollection.ts';
+import type { RangeContributionsFragment } from './generated/stats.ts';
+import type { GraphQLDocument } from './graphqlDocument.ts';
+import { graphqlDocument } from './graphqlDocument.ts';
 
 interface ContributionsQueryVariables {
   login: string;
 }
 
 interface ContributionsQuery {
-  user: Record<`year_${number}`, YearContributionsFragment> | null;
+  user: Record<`range_${number}`, RangeContributionsFragment> | null;
 }
 
 /**
- * Build the all-time contributions query, one aliased `contributionsCollection` field per year.
- * The shape is only known at runtime.
+ * Build the contributions query for a set of ranges. The shape is only known at runtime.
  *
- * @param years Contribution years, one `year_<year>` alias each.
  * @returns Document for `createGraphQLFetcher`.
  */
-const buildContributionsDocument = (years: Array<number>) => {
-  const yearFields = years
-    .map((year) => {
-      const { from, to } = getGitHubYearRange(year);
-      return `year_${year}: contributionsCollection(from: "${toGitHubDateTime(from)}", to: "${toGitHubDateTime(to)}") { ...YearContributions }`;
-    })
-    .join('\n');
-
+const buildContributionsDocument = (
+  ranges: Array<GitHubDateRange>,
+): GraphQLDocument<ContributionsQuery, ContributionsQueryVariables> =>
   // fragment must match queries/stats.graphql, which generates its type
-  return graphqlDocument<ContributionsQuery, ContributionsQueryVariables>(`
+  graphqlDocument<ContributionsQuery, ContributionsQueryVariables>(`
 query userContributions($login: String!) {
   user(login: $login) {
-    ${yearFields}
+    ${aliasedRanges(ranges, 'RangeContributions')}
   }
 }
-fragment YearContributions on ContributionsCollection {
+fragment RangeContributions on ContributionsCollection {
+  totalCommitContributions
   contributionCalendar {
     totalContributions
   }
 }`);
-};
 
 export { buildContributionsDocument };
 export type { ContributionsQuery };

package/src/graphql/generated/contributed-to.ts

@@ -0,0 +1,25 @@
+// Generated file — see .github/CONTRIBUTING.md
+
+/** Internal type. DO NOT USE DIRECTLY. */
+type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
+import { graphqlDocument } from '../graphqlDocument.ts';
+export type UserContributionYearsQueryVariables = Exact<{
+  login: string;
+}>;
+
+export type UserContributionYearsQuery = {
+  user: { login: string; contributionsCollection: { contributionYears: Array<number> } } | null;
+};
+
+export const UserContributionYearsDocument = graphqlDocument<
+  UserContributionYearsQuery,
+  UserContributionYearsQueryVariables
+>(`
+query userContributionYears($login: String!) {
+  user(login: $login) {
+    login
+    contributionsCollection {
+      contributionYears
+    }
+  }
+}`);

package/src/graphql/generated/gist.ts

@@ -2,7 +2,7 @@
 
 /** Internal type. DO NOT USE DIRECTLY. */
 type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
-import { graphqlDocument } from '../graphqlDocument.js';
+import { graphqlDocument } from '../graphqlDocument.ts';
 export type GistFileInfoFragment = {
   name: string | null;
   size: number | null;

package/src/graphql/generated/repo.ts

@@ -2,7 +2,7 @@
 
 /** Internal type. DO NOT USE DIRECTLY. */
 type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
-import { graphqlDocument } from '../graphqlDocument.js';
+import { graphqlDocument } from '../graphqlDocument.ts';
 export type RepoInfoFragment = {
   name: string;
   nameWithOwner: string;

package/src/graphql/generated/stats.ts

@@ -2,9 +2,9 @@
 
 /** Internal type. DO NOT USE DIRECTLY. */
 type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
-import { graphqlDocument } from '../graphqlDocument.js';
+import { graphqlDocument } from '../graphqlDocument.ts';
 
-import type * as Types from './common.js';
+import type * as Types from './common.ts';
 export type RepoNodeFragment = { name: string; stargazerCount: number };
 
 export type RepoStarsFragment = {
@@ -42,6 +42,7 @@ export type UserInfoQueryVariables = Exact<{
   includeDiscussions: boolean;
   includeDiscussionsAnswers: boolean;
   startTime?: string | null | undefined;
+  endTime?: string | null | undefined;
   ownerAffiliations?:
     | Array<Types.RepositoryAffiliation | null | undefined>
     | Types.RepositoryAffiliation
@@ -73,12 +74,24 @@ export type UserInfoQuery = {
   } | null;
 };
 
-export type YearContributionsFragment = { contributionCalendar: { totalContributions: number } };
+export type RangeContributionsFragment = {
+  totalCommitContributions: number;
+  contributionCalendar: { totalContributions: number };
+};
 
 export type RangeContributionsByRepoFragment = {
-  commitContributionsByRepository: Array<{ repository: { nameWithOwner: string } }>;
-  issueContributionsByRepository: Array<{ repository: { nameWithOwner: string } }>;
-  pullRequestContributionsByRepository: Array<{ repository: { nameWithOwner: string } }>;
+  commitContributionsByRepository: Array<{
+    repository: { nameWithOwner: string };
+    contributions: { totalCount: number };
+  }>;
+  issueContributionsByRepository: Array<{
+    repository: { nameWithOwner: string };
+    contributions: { totalCount: number };
+  }>;
+  pullRequestContributionsByRepository: Array<{
+    repository: { nameWithOwner: string };
+    contributions: { totalCount: number };
+  }>;
   repositoryContributions?: {
     nodes: Array<{ repository: { nameWithOwner: string } } | null> | null;
   };
@@ -113,11 +126,11 @@ fragment RepoNode on Repository {
 }`);
 
 export const UserInfoDocument = graphqlDocument<UserInfoQuery, UserInfoQueryVariables>(`
-query userInfo($login: String!, $after: String, $includeMergedPullRequests: Boolean!, $includeDiscussions: Boolean!, $includeDiscussionsAnswers: Boolean!, $startTime: DateTime = null, $ownerAffiliations: [RepositoryAffiliation], $includeUserRepositories: Boolean!) {
+query userInfo($login: String!, $after: String, $includeMergedPullRequests: Boolean!, $includeDiscussions: Boolean!, $includeDiscussionsAnswers: Boolean!, $startTime: DateTime = null, $endTime: DateTime = null, $ownerAffiliations: [RepositoryAffiliation], $includeUserRepositories: Boolean!) {
   user(login: $login) {
     name
     login
-    commits: contributionsCollection(from: $startTime) {
+    commits: contributionsCollection(from: $startTime, to: $endTime) {
       totalCommitContributions
     }
     reviews: contributionsCollection {

package/src/graphql/generated/top-languages.ts

@@ -2,9 +2,9 @@
 
 /** Internal type. DO NOT USE DIRECTLY. */
 type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
-import { graphqlDocument } from '../graphqlDocument.js';
+import { graphqlDocument } from '../graphqlDocument.ts';
 
-import type * as Types from './common.js';
+import type * as Types from './common.ts';
 export type TopLanguageFragment = { size: number; node: { color: string | null; name: string } };
 
 export type TopLanguagesRepositoryFragment = {

package/src/graphql/graphqlDocument.ts

@@ -3,7 +3,7 @@
  *
  * `text` is what goes over the wire; the other two members only carry types and are never assigned.
  * Documents are generated from `queries/*.graphql`
- * See `scripts/generate-graphql-types.js`.
+ * See `scripts/generate-graphql-types.ts`.
  */
 interface GraphQLDocument<TResult, TVariables> {
   readonly text: string;
@@ -14,7 +14,6 @@ interface GraphQLDocument<TResult, TVariables> {
 /**
  * Build a typed document.
  *
- * @param text The query text, including every fragment it spreads.
  * @returns The document to pass to the function created by `createGraphQLFetcher`.
  */
 const graphqlDocument = <TResult, TVariables>(

package/src/graphql/queries/contributed-to.graphql

@@ -0,0 +1,8 @@
+query userContributionYears($login: String!) {
+  user(login: $login) {
+    login
+    contributionsCollection {
+      contributionYears
+    }
+  }
+}

package/src/graphql/queries/stats.graphql

@@ -34,13 +34,14 @@ query userInfo(
   $includeDiscussions: Boolean!
   $includeDiscussionsAnswers: Boolean!
   $startTime: DateTime = null
+  $endTime: DateTime = null
   $ownerAffiliations: [RepositoryAffiliation]
   $includeUserRepositories: Boolean!
 ) {
   user(login: $login) {
     name
     login
-    commits: contributionsCollection(from: $startTime) {
+    commits: contributionsCollection(from: $startTime, to: $endTime) {
       totalCommitContributions
     }
     reviews: contributionsCollection {
@@ -81,27 +82,38 @@ query userInfo(
   }
 }
 
-fragment YearContributions on ContributionsCollection {
+fragment RangeContributions on ContributionsCollection {
+  totalCommitContributions
   contributionCalendar {
     totalContributions
   }
 }
 
+# `contributions` takes no slicing argument on purpose: `totalCount` alone costs no nodes.
 fragment RangeContributionsByRepo on ContributionsCollection {
   commitContributionsByRepository(maxRepositories: $maxRepositories) {
     repository {
       nameWithOwner
     }
+    contributions {
+      totalCount
+    }
   }
   issueContributionsByRepository(maxRepositories: $maxRepositories) {
     repository {
       nameWithOwner
     }
+    contributions {
+      totalCount
+    }
   }
   pullRequestContributionsByRepository(maxRepositories: $maxRepositories) {
     repository {
       nameWithOwner
     }
+    contributions {
+      totalCount
+    }
   }
   repositoryContributions(first: $maxRepositories) @include(if: $includeOwnRepos) {
     nodes {

package/src/graphql/reposContributedToDocument.ts

@@ -1,8 +1,9 @@
-import type { GitHubDateRange } from '../common/date.js';
-import { toGitHubDateTime } from '../common/date.js';
+import type { GitHubDateRange } from '../common/date.ts';
 
-import type { RangeContributionsByRepoFragment } from './generated/stats.js';
-import { graphqlDocument } from './graphqlDocument.js';
+import { aliasedRanges } from './contributionsCollection.ts';
+import type { RangeContributionsByRepoFragment } from './generated/stats.ts';
+import type { GraphQLDocument } from './graphqlDocument.ts';
+import { graphqlDocument } from './graphqlDocument.ts';
 
 /** max value GitHub allows for `first/maxRepositories` */
 const MAX_REPOSITORIES_LIMIT = 100;
@@ -24,21 +25,12 @@ interface ReposContributedToQuery {
  * Mirrors the `contributionTypes: [COMMIT, ISSUE, PULL_REQUEST, REPOSITORY]`
  * filter used by `repositoriesContributedTo` in `stats.graphql`.
  *
- * @param ranges Ranges to fetch, one `range_<index>` alias each.
- * @param includeOwnRepos Whether to select `repositoryContributions`.
  * @returns Document for `createGraphQLFetcher`.
  */
 const buildReposContributedToDocument = (
   ranges: Array<GitHubDateRange>,
   includeOwnRepos: boolean,
-) => {
-  const rangeFields = ranges
-    .map(
-      ({ from, to }, index) =>
-        `range_${index}: contributionsCollection(from: "${toGitHubDateTime(from)}", to: "${toGitHubDateTime(to)}") { ...RangeContributionsByRepo }`,
-    )
-    .join('\n');
-
+): GraphQLDocument<ReposContributedToQuery, ReposContributedToQueryVariables> => {
   // `repositoryContributions` only ever returns repos the user owns,
   // so it is left out rather than gated with @include: an excluded field still counts toward the query's node cost.
   // stats.graphql carries the directive so the generated type marks the field optional.
@@ -56,7 +48,7 @@ const buildReposContributedToDocument = (
   return graphqlDocument<ReposContributedToQuery, ReposContributedToQueryVariables>(`
 query userReposContributedTo($login: String!, $maxRepositories: Int!) {
   user(login: $login) {
-    ${rangeFields}
+    ${aliasedRanges(ranges, 'RangeContributionsByRepo')}
   }
 }
 fragment RangeContributionsByRepo on ContributionsCollection {
@@ -64,16 +56,25 @@ fragment RangeContributionsByRepo on ContributionsCollection {
     repository {
       nameWithOwner
     }
+    contributions {
+      totalCount
+    }
   }
   issueContributionsByRepository(maxRepositories: $maxRepositories) {
     repository {
       nameWithOwner
     }
+    contributions {
+      totalCount
+    }
   }
   pullRequestContributionsByRepository(maxRepositories: $maxRepositories) {
     repository {
       nameWithOwner
     }
+    contributions {
+      totalCount
+    }
   }
   ${ownRepoField}
 }`);