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

package/src/api/stats.ts

@@ -0,0 +1,195 @@
+import * as z from 'zod/mini';
+
+import { RANK_ICONS, renderStatsCard } from '../cards/stats.js';
+import type { CardConfig } from '../common/config.js';
+import { fetchStats } from '../fetchers/stats.js';
+
+import type { ApiResult } from './api-result.js';
+import { errorResult } from './api-result.js';
+import type { ApiQuery } from './params.js';
+import {
+  booleanParam,
+  enumParam,
+  listParam,
+  localeParam,
+  looseIntParam,
+  numberParam,
+  parseColorParams,
+  parseParams,
+  rawParam,
+  safeListParam,
+  safeParam,
+  yearParam,
+} from './params.js';
+
+/** What the stats endpoint accepts, on top of the shared color params. */
+const statsQuery = z.object({
+  username: safeParam,
+  repo: safeListParam,
+  owner: safeListParam,
+  hide: listParam,
+  hide_title: booleanParam,
+  hide_border: booleanParam,
+  card_width: looseIntParam,
+  hide_rank: booleanParam,
+  show_icons: booleanParam,
+  include_all_commits: booleanParam,
+  commits_year: yearParam,
+  line_height: rawParam,
+  text_bold: booleanParam,
+  exclude_repo: listParam,
+  custom_title: rawParam,
+  locale: localeParam,
+  disable_animations: booleanParam,
+  border_radius: numberParam,
+  number_format: rawParam,
+  role: listParam,
+  number_precision: looseIntParam,
+  rank_icon: enumParam(RANK_ICONS),
+  show: listParam,
+  contribs_include_own_repos: booleanParam,
+});
+
+/** The query this endpoint accepts, checked against the schema above. */
+type StatsApiQuery = ApiQuery<typeof statsQuery>;
+
+/**
+ * Render the stats card for a set of query params.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.username GitHub username.
+ * @param query.repo Comma-separated repositories the search-based stats are scoped to.
+ * @param query.owner Comma-separated owners the search-based stats are scoped to.
+ * @param query.hide Comma-separated stats to hide.
+ * @param query.hide_title Whether to hide the card title.
+ * @param query.hide_border Whether to hide the card border.
+ * @param query.card_width Card width.
+ * @param query.hide_rank Whether to hide the rank circle.
+ * @param query.show_icons Whether to show the stat icons.
+ * @param query.include_all_commits Whether to count commits of all time.
+ * @param query.commits_year Year the commits are counted for.
+ * @param query.line_height Line height between the stats.
+ * @param query.text_bold Whether the stat values are bold.
+ * @param query.exclude_repo Comma-separated repositories to exclude.
+ * @param query.custom_title Card title.
+ * @param query.locale Language the card is rendered in.
+ * @param query.disable_animations Whether to disable the card animations.
+ * @param query.border_radius Card border radius.
+ * @param query.number_format How numbers are abbreviated.
+ * @param query.role Comma-separated owner affiliations to include.
+ * @param query.number_precision Decimals kept when a number is abbreviated.
+ * @param query.rank_icon Which rank indicator to draw.
+ * @param query.show Comma-separated extra stats to show.
+ * @param query.contribs_include_own_repos Whether the contributed-to counts include the user's own repositories.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns The rendered card, or a rendered error.
+ */
+const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<ApiResult> => {
+  let colors;
+  try {
+    colors = parseColorParams(query);
+  } catch (err) {
+    // A rejected color cannot be used to draw its own error card.
+    return errorResult(err);
+  }
+
+  try {
+    const {
+      username,
+      repo,
+      owner,
+      hide,
+      hide_title,
+      hide_border,
+      card_width,
+      hide_rank,
+      show_icons,
+      include_all_commits,
+      commits_year,
+      line_height,
+      text_bold,
+      exclude_repo,
+      custom_title,
+      locale,
+      disable_animations,
+      border_radius,
+      number_format,
+      role,
+      number_precision,
+      rank_icon,
+      show,
+      contribs_include_own_repos,
+    } = parseParams(statsQuery, query);
+
+    // A bare repo name is scoped to the user whose card this is.
+    const repository = repo.map((name) =>
+      name.includes('/') ? name : `${username ?? ''}/${name}`,
+    );
+
+    const stats = await fetchStats(
+      {
+        username,
+        include_all_commits,
+        exclude_repo,
+        include_merged_pull_requests:
+          show.includes('prs_merged') || show.includes('prs_merged_percentage'),
+        include_discussions: show.includes('discussions_started'),
+        include_discussions_answers: show.includes('discussions_answered'),
+        commits_year,
+        repo: repository,
+        owner,
+        include_prs_authored: show.includes('prs_authored'),
+        include_prs_commented: show.includes('prs_commented'),
+        include_prs_reviewed: show.includes('prs_reviewed'),
+        include_issues_authored: show.includes('issues_authored'),
+        include_issues_commented: show.includes('issues_commented'),
+        ownerAffiliations: role,
+        include_contributions: show.includes('contributions'),
+        include_all_time_contribs: show.includes('all_time_contribs'),
+        contribs_include_own_repos,
+      },
+      config,
+    );
+
+    return {
+      status: 'success',
+      content: renderStatsCard(
+        stats,
+        {
+          ...colors,
+          hide,
+          show_icons,
+          hide_title,
+          hide_border,
+          card_width,
+          hide_rank,
+          include_all_commits,
+          commits_year,
+          line_height,
+          text_bold,
+          custom_title,
+          border_radius,
+          number_format,
+          number_precision,
+          locale,
+          disable_animations,
+          rank_icon,
+          show,
+        },
+        username,
+        repository,
+        owner,
+      ),
+    };
+  } catch (err) {
+    return errorResult(err, colors);
+  }
+};
+
+/**
+ * The card, with the values its enum params accept.
+ * A UI reads them off the function it calls, e.g. `stats.LAYOUTS`.
+ */
+export const stats = Object.assign(renderStats, {
+  RANK_ICONS,
+});

package/src/api/top-langs.ts

@@ -0,0 +1,150 @@
+import * as z from 'zod/mini';
+
+import {
+  TOP_LANG_LAYOUTS,
+  TOP_LANG_STATS_FORMATS,
+  renderTopLanguages,
+} from '../cards/top-languages.js';
+import type { CardConfig } from '../common/config.js';
+import { fetchTopLanguages } from '../fetchers/top-languages.js';
+
+import type { ApiResult } from './api-result.js';
+import { errorResult } from './api-result.js';
+import type { ApiQuery } from './params.js';
+import {
+  booleanParam,
+  enumParam,
+  listParam,
+  localeParam,
+  looseIntParam,
+  numberParam,
+  parseColorParams,
+  parseParams,
+  rawParam,
+  safeParam,
+} from './params.js';
+
+/** What the top-languages endpoint accepts, on top of the shared color params. */
+const topLangsQuery = z.object({
+  username: safeParam,
+  hide: listParam,
+  hide_title: booleanParam,
+  hide_border: booleanParam,
+  card_width: looseIntParam,
+  layout: enumParam(TOP_LANG_LAYOUTS),
+  langs_count: looseIntParam,
+  exclude_repo: listParam,
+  size_weight: numberParam,
+  count_weight: numberParam,
+  custom_title: rawParam,
+  locale: localeParam,
+  border_radius: numberParam,
+  role: listParam,
+  disable_animations: booleanParam,
+  hide_progress: booleanParam,
+  hide_values: booleanParam,
+  stats_format: enumParam(TOP_LANG_STATS_FORMATS),
+});
+
+/** The query this endpoint accepts, checked against the schema above. */
+type TopLangsApiQuery = ApiQuery<typeof topLangsQuery>;
+
+/**
+ * Render the top languages card for a set of query params.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.username GitHub username.
+ * @param query.hide Comma-separated languages to hide.
+ * @param query.hide_title Whether to hide the card title.
+ * @param query.hide_border Whether to hide the card border.
+ * @param query.card_width Card width.
+ * @param query.layout How the languages are laid out.
+ * @param query.langs_count Number of languages to show.
+ * @param query.exclude_repo Comma-separated repositories to exclude.
+ * @param query.size_weight Weight given to a language's size.
+ * @param query.count_weight Weight given to a language's repository count.
+ * @param query.custom_title Card title.
+ * @param query.locale Language the card is rendered in.
+ * @param query.border_radius Card border radius.
+ * @param query.role Comma-separated owner affiliations to include.
+ * @param query.disable_animations Whether to disable the card animations.
+ * @param query.hide_progress Whether to hide the progress bars.
+ * @param query.hide_values Whether to hide the language values.
+ * @param query.stats_format Whether values are shown as bytes or percentages.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns The rendered card, or a rendered error.
+ */
+const renderTopLangs = async (query: TopLangsApiQuery, config: CardConfig): Promise<ApiResult> => {
+  let colors;
+  try {
+    colors = parseColorParams(query);
+  } catch (err) {
+    // A rejected color cannot be used to draw its own error card.
+    return errorResult(err);
+  }
+
+  try {
+    const {
+      username,
+      hide,
+      hide_title,
+      hide_border,
+      card_width,
+      layout,
+      langs_count,
+      exclude_repo,
+      size_weight,
+      count_weight,
+      custom_title,
+      locale,
+      border_radius,
+      role,
+      disable_animations,
+      hide_progress,
+      hide_values,
+      stats_format,
+    } = parseParams(topLangsQuery, query);
+
+    const topLangs = await fetchTopLanguages(
+      {
+        username,
+        exclude_repo,
+        size_weight,
+        count_weight,
+        ownerAffiliations: role,
+      },
+      config,
+    );
+
+    return {
+      status: 'success',
+      content: renderTopLanguages(topLangs, {
+        ...colors,
+        custom_title,
+        hide_title,
+        hide_border,
+        card_width,
+        hide,
+        layout,
+        langs_count,
+        border_radius,
+        locale,
+        disable_animations,
+        hide_progress,
+        hide_values,
+        stats_format,
+      }),
+    };
+  } catch (err) {
+    return errorResult(err, colors);
+  }
+};
+
+/**
+ * The card, with the values its enum params accept.
+ * A UI reads them off the function it calls, e.g. `topLangs.LAYOUTS`.
+ */
+export const topLangs = Object.assign(renderTopLangs, {
+  LAYOUTS: TOP_LANG_LAYOUTS,
+  STATS_FORMATS: TOP_LANG_STATS_FORMATS,
+});

package/src/api/wakatime.ts

@@ -0,0 +1,130 @@
+import * as z from 'zod/mini';
+
+import { DISPLAY_FORMATS, WAKATIME_LAYOUTS, renderWakatimeCard } from '../cards/wakatime.js';
+import type { CardConfig } from '../common/config.js';
+import { fetchWakatimeStats } from '../fetchers/wakatime.js';
+
+import type { ApiResult } from './api-result.js';
+import { errorResult } from './api-result.js';
+import type { ApiQuery } from './params.js';
+import {
+  booleanParam,
+  enumParam,
+  listParam,
+  localeParam,
+  looseIntParam,
+  numberParam,
+  parseColorParams,
+  parseParams,
+  rawParam,
+  safeParam,
+} from './params.js';
+
+/** What the wakatime endpoint accepts, on top of the shared color params. */
+const wakatimeQuery = z.object({
+  username: safeParam,
+  hide_border: booleanParam,
+  card_width: looseIntParam,
+  line_height: rawParam,
+  hide_title: booleanParam,
+  hide_progress: booleanParam,
+  custom_title: rawParam,
+  locale: localeParam,
+  layout: enumParam(WAKATIME_LAYOUTS),
+  langs_count: looseIntParam,
+  hide: listParam,
+  api_domain: rawParam,
+  border_radius: numberParam,
+  display_format: enumParam(DISPLAY_FORMATS),
+  disable_animations: booleanParam,
+});
+
+/** The query this endpoint accepts, checked against the schema above. */
+type WakatimeApiQuery = ApiQuery<typeof wakatimeQuery>;
+
+/**
+ * Render the WakaTime card for a set of query params.
+ *
+ * WakaTime needs no GitHub token, so the config is read only for the transport it carries.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.username WakaTime username.
+ * @param query.hide_border Whether to hide the card border.
+ * @param query.card_width Card width.
+ * @param query.line_height Line height between the languages.
+ * @param query.hide_title Whether to hide the card title.
+ * @param query.hide_progress Whether to hide the progress bars.
+ * @param query.custom_title Card title.
+ * @param query.locale Language the card is rendered in.
+ * @param query.layout How the languages are laid out.
+ * @param query.langs_count Number of languages to show.
+ * @param query.hide Comma-separated languages to hide.
+ * @param query.api_domain WakaTime instance the stats are read from.
+ * @param query.border_radius Card border radius.
+ * @param query.display_format Whether values are shown as time or percentages.
+ * @param query.disable_animations Whether to disable the card animations.
+ * @param config Deployment config supplying the transport.
+ * @returns The rendered card, or a rendered error.
+ */
+const renderWakatime = async (query: WakatimeApiQuery, config: CardConfig): Promise<ApiResult> => {
+  let colors;
+  try {
+    colors = parseColorParams(query);
+  } catch (err) {
+    // A rejected color cannot be used to draw its own error card.
+    return errorResult(err);
+  }
+
+  try {
+    const {
+      username,
+      hide_border,
+      card_width,
+      line_height,
+      hide_title,
+      hide_progress,
+      custom_title,
+      locale,
+      layout,
+      langs_count,
+      hide,
+      api_domain,
+      border_radius,
+      display_format,
+      disable_animations,
+    } = parseParams(wakatimeQuery, query);
+
+    const stats = await fetchWakatimeStats({ username, api_domain }, config);
+
+    return {
+      status: 'success',
+      content: renderWakatimeCard(stats, {
+        ...colors,
+        custom_title,
+        hide_title,
+        hide_border,
+        card_width,
+        hide,
+        line_height,
+        hide_progress,
+        border_radius,
+        locale,
+        layout,
+        langs_count,
+        display_format,
+        disable_animations,
+      }),
+    };
+  } catch (err) {
+    return errorResult(err, colors);
+  }
+};
+
+/**
+ * The card, with the values its enum params accept.
+ * A UI reads them off the function it calls, e.g. `wakatime.LAYOUTS`.
+ */
+export const wakatime = Object.assign(renderWakatime, {
+  LAYOUTS: WAKATIME_LAYOUTS,
+  DISPLAY_FORMATS,
+});

package/src/calculateRank.ts

@@ -0,0 +1,91 @@
+/**
+ * Calculates the exponential cdf.
+ *
+ * @param x The value.
+ * @returns The exponential cdf.
+ */
+function exponential_cdf(x: number): number {
+  return 1 - 2 ** -x;
+}
+
+/**
+ * Calculates the log normal cdf.
+ *
+ * @param x The value.
+ * @returns The log normal cdf.
+ */
+function log_normal_cdf(x: number): number {
+  // approximation
+  return x / (1 + x);
+}
+
+/**
+ * Calculates the users rank.
+ *
+ * @param params Parameters on which the user's rank depends.
+ * @param params.all_commits Whether `include_all_commits` was used.
+ * @param params.commits Number of commits.
+ * @param params.prs The number of pull requests.
+ * @param params.issues The number of issues.
+ * @param params.reviews The number of reviews.
+ * @param params.repos Total number of repos (accepted for compatibility, unused in the calculation).
+ * @param params.stars The number of stars.
+ * @param params.followers The number of followers.
+ * @returns The users rank.
+ */
+function calculateRank({
+  all_commits,
+  commits,
+  prs,
+  issues,
+  reviews,
+  stars,
+  followers,
+}: {
+  all_commits: boolean;
+  commits: number;
+  prs: number;
+  issues: number;
+  reviews: number;
+  repos: number;
+  stars: number;
+  followers: number;
+}): { level: string; percentile: number } {
+  const COMMITS_MEDIAN = all_commits ? 1000 : 250,
+    COMMITS_WEIGHT = 2;
+  const PRS_MEDIAN = 50,
+    PRS_WEIGHT = 3;
+  const ISSUES_MEDIAN = 25,
+    ISSUES_WEIGHT = 1;
+  const REVIEWS_MEDIAN = 2,
+    REVIEWS_WEIGHT = 1;
+  const STARS_MEDIAN = 50,
+    STARS_WEIGHT = 4;
+  const FOLLOWERS_MEDIAN = 10,
+    FOLLOWERS_WEIGHT = 1;
+
+  const TOTAL_WEIGHT =
+    COMMITS_WEIGHT + PRS_WEIGHT + ISSUES_WEIGHT + REVIEWS_WEIGHT + STARS_WEIGHT + FOLLOWERS_WEIGHT;
+
+  const THRESHOLDS = [1, 12.5, 25, 37.5, 50, 62.5, 75, 87.5, 100];
+  const LEVELS = ['S', 'A+', 'A', 'A-', 'B+', 'B', 'B-', 'C+', 'C'];
+
+  const rank =
+    1 -
+    (COMMITS_WEIGHT * exponential_cdf(commits / COMMITS_MEDIAN) +
+      PRS_WEIGHT * exponential_cdf(prs / PRS_MEDIAN) +
+      ISSUES_WEIGHT * exponential_cdf(issues / ISSUES_MEDIAN) +
+      REVIEWS_WEIGHT * exponential_cdf(reviews / REVIEWS_MEDIAN) +
+      STARS_WEIGHT * log_normal_cdf(stars / STARS_MEDIAN) +
+      FOLLOWERS_WEIGHT * log_normal_cdf(followers / FOLLOWERS_MEDIAN)) /
+      TOTAL_WEIGHT;
+
+  const level = LEVELS[THRESHOLDS.findIndex((t) => rank * 100 <= t)];
+  if (level === undefined) {
+    throw new Error('Unable to determine rank level');
+  }
+
+  return { level, percentile: rank * 100 };
+}
+
+export { calculateRank };