@stats-forge/github-stats-forge-core 0.0.1

package/src/fetchers/top-languages.ts

@@ -0,0 +1,134 @@
+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 {
+  TopLanguageFragment,
+  TopLanguagesRepositoryFragment,
+} from '../graphql/generated/top-languages.js';
+
+import type { Lang, TopLangData } from './types.js';
+
+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 (
+  {
+    username,
+    exclude_repo = [],
+    size_weight = 1,
+    count_weight = 0,
+    ownerAffiliations = [],
+  }: {
+    username: string | undefined;
+    exclude_repo?: Array<string>;
+    size_weight?: number | undefined;
+    count_weight?: number | undefined;
+    ownerAffiliations?: Array<string>;
+  },
+  config: CardConfig,
+): Promise<TopLangData> => {
+  if (!username) {
+    throw CardError.missingParam(['username']);
+  }
+  const affiliations = parseOwnerAffiliations(ownerAffiliations);
+
+  const res = await retryer(
+    fetcher,
+    {
+      login: username,
+      ownerAffiliations: affiliations,
+    },
+    config,
+  );
+
+  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(
+      'Something went wrong while trying to retrieve the language data using the GraphQL API.',
+      { code: 'upstream' },
+    );
+  }
+
+  const repoToHide: Record<string, boolean> = {};
+  const allExcludedRepos = [...exclude_repo, ...config.excludeRepositories];
+
+  // populate repoToHide map for quick lookup while filtering out
+  allExcludedRepos.forEach((repoName) => {
+    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) => {
+    const edges = (repo.languages?.edges ?? []).filter(
+      (edge): edge is TopLanguageFragment => !!edge,
+    );
+    return edges.length > 0 ? edges.concat(acc) : acc;
+  }, []);
+
+  // accumulate size and repo count per language
+  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,
+    };
+  }
+
+  // comparison index calculation
+  for (const lang of Object.values(languageMap)) {
+    lang.size = Math.pow(lang.size, size_weight) * Math.pow(lang.count, count_weight);
+  }
+
+  // return languages sorted by (weighted) size, descending
+  return Object.fromEntries(Object.entries(languageMap).sort(([, a], [, b]) => b.size - a.size));
+};
+
+export { fetchTopLanguages };

package/src/fetchers/types.ts

@@ -0,0 +1,136 @@
+import type { RepoInfoFragment } from '../graphql/generated/repo.js';
+
+export interface GistData {
+  name: string;
+  nameWithOwner: string;
+  description: string | null;
+  language: string | null;
+  starsCount: number;
+  forksCount: number;
+}
+
+/**
+ * What the repo query returns, with `primaryLanguage` loosened:
+ * the schema says `name` is non-null, but the card falls back to defaults for callers passing untyped data.
+ */
+type RepoInfo = Omit<RepoInfoFragment, 'primaryLanguage'> & {
+  primaryLanguage: {
+    color: string | null;
+    id?: string;
+    name: string | null;
+  } | null;
+};
+
+export interface RepoUserStats {
+  // only present when the matching include_* flag is set (see fetchRepoUserStats)
+  totalPRsAuthored?: number;
+  totalPRsCommented?: number;
+  totalPRsReviewed?: number;
+  totalIssuesAuthored?: number;
+  totalIssuesCommented?: number;
+}
+
+export type RepositoryData = RepoInfo & RepoUserStats;
+
+export interface StatsData {
+  name: string;
+  totalPRs: number;
+  totalPRsMerged: number;
+  mergedPRsPercentage: number;
+  totalReviews: number;
+  totalCommits: number;
+  totalIssues: number;
+  totalStars: number;
+  totalDiscussionsStarted: number;
+  totalDiscussionsAnswered: number;
+  contributedTo: number;
+  allTimeContributedTo: number;
+  totalPRsAuthored: number;
+  totalPRsCommented: number;
+  totalPRsReviewed: number;
+  totalIssuesAuthored: number;
+  totalIssuesCommented: number;
+  totalContributions: number;
+  rank: { level: string; percentile: number };
+}
+
+export interface Lang {
+  name: string;
+  // GitHub's GraphQL `Language.color` is nullable — the card falls back to a default.
+  color: string | null;
+  size: number;
+  /** Number of repositories the language appears in. */
+  count: number;
+}
+
+export type TopLangData = Record<string, Lang>;
+
+export interface WakaTimeData {
+  categories: Array<{
+    digital: string;
+    hours: number;
+    minutes: number;
+    name: string;
+    percent: number;
+    text: string;
+    total_seconds: number;
+  }>;
+  daily_average: number;
+  daily_average_including_other_language: number;
+  days_including_holidays: number;
+  days_minus_holidays: number;
+  editors: Array<{
+    digital: string;
+    hours: number;
+    minutes: number;
+    name: string;
+    percent: number;
+    text: string;
+    total_seconds: number;
+  }>;
+  holidays: number;
+  human_readable_daily_average: string;
+  human_readable_daily_average_including_other_language: string;
+  human_readable_total: string;
+  human_readable_total_including_other_language: string;
+  id: string;
+  is_already_updating: boolean;
+  is_coding_activity_visible: boolean;
+  is_including_today: boolean;
+  is_other_usage_visible: boolean;
+  is_stuck: boolean;
+  is_up_to_date: boolean;
+  languages: Array<{
+    digital: string;
+    hours: number;
+    minutes: number;
+    name: string;
+    percent: number;
+    text: string;
+    total_seconds: number;
+  }>;
+  operating_systems: Array<{
+    digital: string;
+    hours: number;
+    minutes: number;
+    name: string;
+    percent: number;
+    text: string;
+    total_seconds: number;
+  }>;
+  percent_calculated: number;
+  range: string;
+  status: string;
+  timeout: number;
+  total_seconds: number;
+  total_seconds_including_other_language: number;
+  user_id: string;
+  username: string;
+  writes_only: boolean;
+}
+
+export interface WakaTimeLang {
+  name: string;
+  text: string;
+  percent: number;
+}

package/src/fetchers/wakatime.ts

@@ -0,0 +1,56 @@
+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 { WakaTimeData } from './types.js';
+
+/**
+ * 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 (
+  {
+    username,
+    api_domain,
+  }: {
+    username: string | undefined;
+    api_domain?: string | undefined;
+  },
+  config: CardConfig,
+): Promise<WakaTimeData> => {
+  if (!username) {
+    throw CardError.missingParam(['username']);
+  }
+
+  const domain = api_domain ? api_domain.replace(/\/$/gi, '') : 'wakatime.com';
+  const res = await httpRequest<{ data: WakaTimeData }>(
+    config.fetch,
+    `https://${domain}/api/v1/users/${username}/stats?is_including_today=true`,
+  );
+
+  // Only a 404 says the profile does not exist.
+  // Any other failure is WakaTime being unavailable, which a retry can still answer,
+  // so it must not be reported as a permanent one a host would cache.
+  if (res.status === 404) {
+    throw new CardError(`Could not resolve to a User with the login of '${username}'`, {
+      code: 'not_found',
+      secondaryMessage: WAKATIME_USER_NOT_FOUND,
+    });
+  }
+  if (res.status < 200 || res.status > 299) {
+    throw new CardError(`Could not fetch the WakaTime stats of '${username}'`, {
+      code: 'upstream',
+    });
+  }
+
+  return res.data.data;
+};
+
+export { fetchWakatimeStats };

package/src/graphql/contributionsDocument.ts

@@ -0,0 +1,44 @@
+import { getGitHubYearRange, toGitHubDateTime } from '../common/date.js';
+
+import type { YearContributionsFragment } from './generated/stats.js';
+import { graphqlDocument } from './graphqlDocument.js';
+
+interface ContributionsQueryVariables {
+  login: string;
+}
+
+interface ContributionsQuery {
+  user: Record<`year_${number}`, YearContributionsFragment> | null;
+}
+
+/**
+ * Build the all-time contributions query, one aliased `contributionsCollection` field per year.
+ * 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');
+
+  // fragment must match queries/stats.graphql, which generates its type
+  return graphqlDocument<ContributionsQuery, ContributionsQueryVariables>(`
+query userContributions($login: String!) {
+  user(login: $login) {
+    ${yearFields}
+  }
+}
+fragment YearContributions on ContributionsCollection {
+  contributionCalendar {
+    totalContributions
+  }
+}`);
+};
+
+export { buildContributionsDocument };
+export type { ContributionsQuery };

package/src/graphql/generated/common.ts

@@ -0,0 +1,26 @@
+// Generated file — see .github/CONTRIBUTING.md
+
+export type Maybe<T> = T | null;
+export type InputMaybe<T> = Maybe<T>;
+/** All built-in and custom scalars, mapped to their actual values */
+export type Scalars = {
+  ID: { input: string; output: string };
+  String: { input: string; output: string };
+  Boolean: { input: boolean; output: boolean };
+  Int: { input: number; output: number };
+  Float: { input: number; output: number };
+  /** An ISO-8601 encoded UTC date string. */
+  DateTime: { input: string; output: string };
+};
+
+/** The affiliation of a user to a repository */
+export type RepositoryAffiliation =
+  /** Repositories that the user has been added to as a collaborator. */
+  | 'COLLABORATOR'
+  /**
+   * Repositories that the user has access to through being a member of an
+   * organization. This includes every repository on every team that the user is on.
+   */
+  | 'ORGANIZATION_MEMBER'
+  /** Repositories that are owned by the authenticated user. */
+  | 'OWNER';

package/src/graphql/generated/gist.ts

@@ -0,0 +1,56 @@
+// 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.js';
+export type GistFileInfoFragment = {
+  name: string | null;
+  size: number | null;
+  language: { name: string } | null;
+};
+
+export type GistInfoQueryVariables = Exact<{
+  gistName: string;
+}>;
+
+export type GistInfoQuery = {
+  viewer: {
+    gist: {
+      description: string | null;
+      stargazerCount: number;
+      owner: { login: string } | { login: string } | null;
+      forks: { totalCount: number };
+      files: Array<{
+        name: string | null;
+        size: number | null;
+        language: { name: string } | null;
+      } | null> | null;
+    } | null;
+  };
+};
+
+export const GistInfoDocument = graphqlDocument<GistInfoQuery, GistInfoQueryVariables>(`
+query gistInfo($gistName: String!) {
+  viewer {
+    gist(name: $gistName) {
+      description
+      owner {
+        login
+      }
+      stargazerCount
+      forks {
+        totalCount
+      }
+      files {
+        ...GistFileInfo
+      }
+    }
+  }
+}
+fragment GistFileInfo on GistFile {
+  name
+  language {
+    name
+  }
+  size
+}`);

package/src/graphql/generated/repo.ts

@@ -0,0 +1,79 @@
+// 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.js';
+export type RepoInfoFragment = {
+  name: string;
+  nameWithOwner: string;
+  isPrivate: boolean;
+  isArchived: boolean;
+  isTemplate: boolean;
+  stargazerCount: number;
+  description: string | null;
+  forkCount: number;
+  primaryLanguage: { color: string | null; id: string; name: string } | null;
+};
+
+export type GetRepoQueryVariables = Exact<{
+  login: string;
+  repo: string;
+}>;
+
+export type GetRepoQuery = {
+  user: {
+    repository: {
+      name: string;
+      nameWithOwner: string;
+      isPrivate: boolean;
+      isArchived: boolean;
+      isTemplate: boolean;
+      stargazerCount: number;
+      description: string | null;
+      forkCount: number;
+      primaryLanguage: { color: string | null; id: string; name: string } | null;
+    } | null;
+  } | null;
+  organization: {
+    repository: {
+      name: string;
+      nameWithOwner: string;
+      isPrivate: boolean;
+      isArchived: boolean;
+      isTemplate: boolean;
+      stargazerCount: number;
+      description: string | null;
+      forkCount: number;
+      primaryLanguage: { color: string | null; id: string; name: string } | null;
+    } | null;
+  } | null;
+};
+
+export const GetRepoDocument = graphqlDocument<GetRepoQuery, GetRepoQueryVariables>(`
+query getRepo($login: String!, $repo: String!) {
+  user(login: $login) {
+    repository(name: $repo) {
+      ...RepoInfo
+    }
+  }
+  organization(login: $login) {
+    repository(name: $repo) {
+      ...RepoInfo
+    }
+  }
+}
+fragment RepoInfo on Repository {
+  name
+  nameWithOwner
+  isPrivate
+  isArchived
+  isTemplate
+  stargazerCount
+  description
+  primaryLanguage {
+    color
+    id
+    name
+  }
+  forkCount
+}`);