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

package/src/common/ops.ts

@@ -40,14 +40,10 @@ const parseArray = (str: string | undefined): Array<string> => {
 /**
  * Clamp the given number between the given range.
  *
- * @returns The clamped number.
+ * @returns The clamped number; `min` for `NaN`.
  */
-const clampValue = (number: string | number, min: number, max: number): number => {
-  if (Number.isNaN(Number.parseInt(String(number), 10))) {
-    return min;
-  }
-  return Math.max(min, Math.min(Number(number), max));
-};
+const clampValue = (number: number, min: number, max: number): number =>
+  Number.isNaN(number) ? min : Math.max(min, Math.min(number, max));
 
 /**
  * Lowercase and trim string.
@@ -112,18 +108,13 @@ const parseOwnerAffiliations = (affiliations: Array<string>): Array<RepositoryAf
   return normalized;
 };
 
-const buildSearchFilter = (
-  repos: Array<string> | string = [],
-  owners: Array<string> | string = [],
-): string => {
-  const repoFilter =
-    Array.isArray(repos) && repos.length > 0 ? repos.map((repo) => `repo:${repo} `).join('') : '';
-  const orgFilter =
-    Array.isArray(owners) && owners.length > 0
-      ? owners.map((owner) => `owner:${owner} `).join('')
-      : '';
-  return repoFilter + orgFilter;
-};
+/**
+ * The qualifiers that scope a REST search to repositories and owners.
+ *
+ * @returns e.g. `repo:a/b owner:c `, each qualifier followed by a space; empty when both lists are.
+ */
+const buildSearchFilter = (repos: Array<string>, owners: Array<string>): string =>
+  [...repos.map((repo) => `repo:${repo} `), ...owners.map((owner) => `owner:${owner} `)].join('');
 
 export {
   parseBoolean,

package/src/common/render.ts

@@ -265,6 +265,13 @@ const iconWithLabel = (
   });
 };
 
+/**
+ * How a stat value is written.
+ * Not validated at the boundary: anything but `long` reads as `short`,
+ * so an unknown value falls back rather than failing.
+ */
+const NUMBER_FORMATS = ['short', 'long'] as const;
+
 /**
  * Create a labelled stat text item
  * (a label and its value, optionally with an icon and link).
@@ -439,10 +446,10 @@ const renderError = ({
         fill: String(bgColor),
         xmlns: 'http://www.w3.org/2000/svg',
         role: 'img',
-        'aria-labelledby': 'titleId descId',
+        'aria-labelledby': 'title-id desc-id',
       },
-      el('title', { id: 'titleId' }, message),
-      el('desc', { id: 'descId' }, secondaryMessage),
+      el('title', { id: 'title-id' }, message),
+      el('desc', { id: 'desc-id' }, secondaryMessage),
       style(
         rule('.text', { font: "600 16px 'Segoe UI', Ubuntu, Sans-Serif", fill: titleColor }),
         rule('.small', { font: "600 12px 'Segoe UI', Ubuntu, Sans-Serif", fill: textColor }),
@@ -468,6 +475,51 @@ const renderError = ({
   );
 };
 
+/** Advance of each ASCII code point, as a fraction of the font size. */
+// prettier-ignore
+const CHAR_WIDTHS = [
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+  0, 0, 0, 0, 0, 0, 0, 0.2733333110809326, 0.28499999046325686,
+  0.39166667461395266, 0.5900000095367431, 0.5383333206176758,
+  0.8183333396911621, 0.8, 0.22999999523162842, 0.30166666507720946,
+  0.30166666507720946, 0.41666665077209475, 0.6833333492279052,
+  0.21666667461395264, 0.4, 0.21666667461395264, 0.3900000095367432,
+  0.5383333206176758, 0.5383333206176758, 0.5383333206176758,
+  0.5383333206176758, 0.5383333206176758, 0.5383333206176758,
+  0.5383333206176758, 0.5383333206176758, 0.5383333206176758,
+  0.5383333206176758, 0.21666667461395264, 0.21666667461395264,
+  0.6833333492279052, 0.6833333492279052, 0.6833333492279052,
+  0.4483333110809326, 0.9550000190734863, 0.6449999809265137,
+  0.5733333110809327, 0.6183333396911621, 0.7016666889190674,
+  0.5066666603088379, 0.48833332061767576, 0.6866666793823242,
+  0.7099999904632568, 0.26666667461395266, 0.35666666030883787,
+  0.5800000190734863, 0.4699999809265137, 0.8983333587646485,
+  0.7483333110809326, 0.753333330154419, 0.5599999904632569,
+  0.753333330154419, 0.5983333110809326, 0.5316666603088379,
+  0.5233333110809326, 0.6866666793823242, 0.621666669845581,
+  0.9333333015441895, 0.5900000095367431, 0.553333330154419,
+  0.5699999809265137, 0.30166666507720946, 0.37833333015441895,
+  0.30166666507720946, 0.6833333492279052, 0.41500000953674315,
+  0.26833333969116213, 0.5083333492279053, 0.5883333206176757,
+  0.4616666793823242, 0.5883333206176757, 0.5233333110809326,
+  0.3133333444595337, 0.5883333206176757, 0.5666666507720948,
+  0.24166667461395264, 0.24166667461395264, 0.49666666984558105,
+  0.24166667461395264, 0.8616666793823242, 0.5666666507720948,
+  0.5866666793823242, 0.5883333206176757, 0.5883333206176757,
+  0.3483333349227905, 0.425, 0.33833334445953367, 0.5666666507720948,
+  0.4783333301544189, 0.7233333110809326, 0.45833334922790525,
+  0.4833333492279053, 0.45166668891906736, 0.30166666507720946,
+  0.24000000953674316, 0.30166666507720946, 0.6833333492279052,
+];
+
+/** Advance of a code point the table does not cover. */
+const AVERAGE_CHAR_WIDTH = 0.5131403493881227;
+/**
+ * Full-width glyphs: U+3000–U+9FFF (CJK symbols and punctuation, Hiragana, Katakana,
+ * CJK Unified Ideographs incl. Extension A) plus U+FF00–U+FFEF (halfwidth and fullwidth forms).
+ */
+const FULL_WIDTH_PATTERN = /[\u3000-\u9FFF\uFF00-\uFFEF]/;
+
 /**
  * Retrieve text length based on Segoe UI font.
  *
@@ -475,65 +527,15 @@ const renderError = ({
  *
  * @returns Text length.
  */
-const measureText = (str: string, fontSize = 10): number => {
-  // prettier-ignore
-  const widths = [
-    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-    0, 0, 0, 0, 0, 0, 0, 0.2733333110809326, 0.28499999046325686,
-    0.39166667461395266, 0.5900000095367431, 0.5383333206176758,
-    0.8183333396911621, 0.8, 0.22999999523162842, 0.30166666507720946,
-    0.30166666507720946, 0.41666665077209475, 0.6833333492279052,
-    0.21666667461395264, 0.4, 0.21666667461395264, 0.3900000095367432,
-    0.5383333206176758, 0.5383333206176758, 0.5383333206176758,
-    0.5383333206176758, 0.5383333206176758, 0.5383333206176758,
-    0.5383333206176758, 0.5383333206176758, 0.5383333206176758,
-    0.5383333206176758, 0.21666667461395264, 0.21666667461395264,
-    0.6833333492279052, 0.6833333492279052, 0.6833333492279052,
-    0.4483333110809326, 0.9550000190734863, 0.6449999809265137,
-    0.5733333110809327, 0.6183333396911621, 0.7016666889190674,
-    0.5066666603088379, 0.48833332061767576, 0.6866666793823242,
-    0.7099999904632568, 0.26666667461395266, 0.35666666030883787,
-    0.5800000190734863, 0.4699999809265137, 0.8983333587646485,
-    0.7483333110809326, 0.753333330154419, 0.5599999904632569,
-    0.753333330154419, 0.5983333110809326, 0.5316666603088379,
-    0.5233333110809326, 0.6866666793823242, 0.621666669845581,
-    0.9333333015441895, 0.5900000095367431, 0.553333330154419,
-    0.5699999809265137, 0.30166666507720946, 0.37833333015441895,
-    0.30166666507720946, 0.6833333492279052, 0.41500000953674315,
-    0.26833333969116213, 0.5083333492279053, 0.5883333206176757,
-    0.4616666793823242, 0.5883333206176757, 0.5233333110809326,
-    0.3133333444595337, 0.5883333206176757, 0.5666666507720948,
-    0.24166667461395264, 0.24166667461395264, 0.49666666984558105,
-    0.24166667461395264, 0.8616666793823242, 0.5666666507720948,
-    0.5866666793823242, 0.5883333206176757, 0.5883333206176757,
-    0.3483333349227905, 0.425, 0.33833334445953367, 0.5666666507720948,
-    0.4783333301544189, 0.7233333110809326, 0.45833334922790525,
-    0.4833333492279053, 0.45166668891906736, 0.30166666507720946,
-    0.24000000953674316, 0.30166666507720946, 0.6833333492279052,
-  ];
-
-  const avg = 0.5131403493881227;
-  // CJK character range: U+3000–U+9FFF (CJK Symbols/Punctuation, Hiragana,
-  // Katakana, CJK Unified Ideographs incl. Extension A) plus U+FF00–U+FFEF
-  // (Halfwidth/Fullwidth Forms — fullwidth ASCII, fullwidth punctuation).
-  const cjkRange = /[\u3000-\u9FFF\uFF00-\uFFEF]/;
-
-  return (
-    [...str]
-      .map((char) => {
-        if (cjkRange.test(char) || char === '\u3000') {
-          // CJK glyphs and U+3000 IDEOGRAPHIC SPACE are full-width by default;
-          return 1;
-        }
-        const code = char.codePointAt(0) ?? 0;
-        if (code < widths.length) {
-          return widths[code] ?? avg;
-        }
-        return avg;
-      })
-      .reduce((cur, acc) => acc + cur) * fontSize
-  );
-};
+const measureText = (str: string, fontSize = 10): number =>
+  [...str]
+    .map((char) => {
+      if (FULL_WIDTH_PATTERN.test(char)) {
+        return 1;
+      }
+      return CHAR_WIDTHS[char.codePointAt(0) ?? 0] ?? AVERAGE_CHAR_WIDTH;
+    })
+    .reduce((total, width) => total + width, 0) * fontSize;
 
 /**
  * Split text into the lines it would wrap to when laid out greedily at the
@@ -673,6 +675,7 @@ const countWrappedLines = (
 ): number => Math.min(Math.max(1, splitWrappedText(text, fontSize, maxWidth).length), maxLines);
 
 export {
+  NUMBER_FORMATS,
   renderError,
   createLanguageNode,
   createProgressNode,

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/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,3 +1,4 @@
+export { fetchContributedTo } from './contributed-to.ts';
 export { fetchGist } from './gist.ts';
 export { fetchRepo } from './repo.ts';
 export { fetchRepoUserStats, fetchStats } from './stats.ts';
@@ -5,6 +6,8 @@ export { fetchTopLanguages } from './top-languages.ts';
 export { fetchWakatimeStats } from './wakatime.ts';
 
 export type {
+  ContributedRepo,
+  ContributedToData,
   GistData,
   Lang,
   RepoUserStats,