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

package/src/common/locales.ts

@@ -0,0 +1,61 @@
+import { defineLocales } from './localize.ts';
+
+/**
+ * The wordings more than one card draws, in the locales they have been translated into.
+ *
+ * `lastYear` lived in the wakatime card's table until 2026-09-08, which is where the
+ * stats card reached for it — the translations here are that table's, moved verbatim.
+ */
+const commonLocales = defineLocales({
+  lastYear: {
+    en: 'last year',
+    ar: 'العام الماضي',
+    az: 'Ötən il',
+    ca: "L'any passat",
+    cn: '去年',
+    'zh-tw': '去年',
+    cs: 'Minulý rok',
+    de: 'Letztes Jahr',
+    sw: 'Mwaka uliopita',
+    ur: 'پچھلا سال',
+    bg: 'миналата год.',
+    bn: 'গত বছর',
+    es: 'El año pasado',
+    fa: 'سال گذشته',
+    fi: 'Viime vuosi',
+    fr: "L'année dernière",
+    hi: 'पिछले साल',
+    sa: 'गतवर्षे',
+    hu: 'Tavaly',
+    it: "L'anno scorso",
+    ja: '昨年',
+    kr: '작년',
+    nl: 'Vorig jaar',
+    'pt-pt': 'Ano passado',
+    'pt-br': 'Ano passado',
+    np: 'गत वर्ष',
+    el: 'Πέρυσι',
+    ro: 'Anul trecut',
+    ru: 'За прошлый год',
+    'uk-ua': 'За минулий рік',
+    id: 'Tahun lalu',
+    ml: 'കഴിഞ്ഞ വർഷം',
+    my: 'မနှစ်က',
+    ta: `கடந்த ஆண்டு`,
+    sk: 'Minulý rok',
+    tr: 'Geçen yıl',
+    pl: 'W zeszłym roku',
+    uz: "O'tgan yil",
+    vi: 'Năm ngoái',
+    se: 'Förra året',
+    he: 'שנה שעברה',
+    fil: 'Nakaraang Taon',
+    th: 'ปีที่แล้ว',
+    sr: 'Прошла год.',
+    'sr-latn': 'Prošla god.',
+    no: 'I fjor',
+    be: 'мінулы год',
+  },
+});
+
+export { commonLocales };

package/src/common/localize.ts

@@ -0,0 +1,251 @@
+/**
+ * Every locale a card can be asked for.
+ *
+ * A key is written in `en` first and translated afterwards, so a card's table need not
+ * carry every locale — a wording falls back to `en`. This list is what the api accepts.
+ *
+ * @see https://www.andiamo.co.uk/resources/iso-language-codes/ for language codes.
+ */
+const AVAILABLE_LOCALES = [
+  'en',
+  'ar',
+  'az',
+  'bg',
+  'bn',
+  'ca',
+  'cn',
+  'zh-tw',
+  'cs',
+  'de',
+  'sw',
+  'ur',
+  'es',
+  'fa',
+  'fi',
+  'fr',
+  'hi',
+  'sa',
+  'hu',
+  'it',
+  'ja',
+  'kr',
+  'nl',
+  'pt-pt',
+  'pt-br',
+  'np',
+  'el',
+  'ro',
+  'ru',
+  'uk-ua',
+  'id',
+  'ml',
+  'my',
+  'ta',
+  'sk',
+  'tr',
+  'pl',
+  'uz',
+  'vi',
+  'se',
+  'he',
+  'fil',
+  'th',
+  'sr',
+  'sr-latn',
+  'no',
+  'be',
+] as const;
+
+const FALLBACK_LOCALE = 'en';
+
+/**
+ * Checks whether the locale is available or not.
+ *
+ * @returns Boolean specifying whether the locale is available or not.
+ */
+const isLocaleAvailable = (locale: string): boolean =>
+  (AVAILABLE_LOCALES as ReadonlyArray<string>).includes(locale.toLowerCase());
+
+/**
+ * A count-dependent wording: one form per plural category the locale distinguishes.
+ *
+ * `other` is the form every locale has, so it is what an unwritten category falls back to.
+ */
+type PluralForms = { other: string } & Partial<Record<Intl.LDMLPluralRule, string>>;
+
+/** One locale's wording for a key, either outright or a form per plural category. */
+type Phrase = string | PluralForms;
+
+/**
+ * A card's translations: a key, then that key's wording per locale.
+ *
+ * `en` is required because it is what every other locale falls back to; the rest are
+ * checked against {@link AVAILABLE_LOCALES} by `tests/locales.test.ts`.
+ */
+type LocaleTable = Record<string, { en: Phrase } & Record<string, Phrase>>;
+
+/**
+ * Declares a card's translations, keeping every string's literal type so `localize` knows
+ * which `{placeholder}` values each key needs.
+ *
+ * @returns The table it was given.
+ */
+const defineLocales = <const Table extends LocaleTable>(table: Table): Table => table;
+
+/** The `{name}` placeholders in a phrase, as a union of their names. */
+type PlaceholderNames<Written> = Written extends `${string}{${infer Name}}${infer Rest}`
+  ? Name | PlaceholderNames<Rest>
+  : never;
+
+/** What a phrase has to be given: its placeholders, plus `count` when it has plural forms. */
+type PhraseValues<Written> =
+  // a wording only known at runtime declares nothing, so it asks for nothing
+  string extends Written
+    ? never
+    : Written extends string
+      ? PlaceholderNames<Written>
+      : Written extends Record<string, string>
+        ? 'count' | PlaceholderNames<Written[keyof Written]>
+        : never;
+
+/** `t`'s trailing argument: absent for a wording that interpolates nothing. */
+type ValuesArg<Written> = [PhraseValues<Written>] extends [never]
+  ? []
+  : [
+      values: {
+        [Name in PhraseValues<Written>]: Name extends 'count' ? number : string | number;
+      },
+    ];
+
+/** The values as `t` reads them back, once the generic tuple above has done its checking. */
+type ReadValues = Record<string, string | number> | undefined;
+
+/** `{name}` — a placeholder in a phrase. */
+const PLACEHOLDER = /\{(?<name>\w+)\}/g;
+
+/**
+ * Substitutes a phrase's `{name}` placeholders. Only the phrase is scanned, so a value
+ * that itself looks like a placeholder is left alone.
+ *
+ * @returns The wording as the card draws it.
+ */
+const interpolate = (phrase: string, key: string, values: ReadValues): string =>
+  phrase.replace(PLACEHOLDER, (_placeholder, name: string) => {
+    const value = values?.[name];
+    if (value === undefined) {
+      throw new Error(`'${key}' needs a value for '{${name}}'`);
+    }
+    return String(value);
+  });
+
+const pluralRules = new Map<string, Intl.PluralRules>();
+
+/**
+ * The plural rules of the locale that supplied the phrase. Several of the locale names
+ * here are not language tags `Intl` knows (`cn`, `kr`, `np`), and resolve to the runtime's
+ * own locale — which only matters once such a locale writes plural forms of its own.
+ *
+ * @returns The rules, built once per locale.
+ */
+const rulesFor = (locale: string): Intl.PluralRules => {
+  const cached = pluralRules.get(locale);
+  if (cached) {
+    return cached;
+  }
+
+  const rules = new Intl.PluralRules(locale);
+  pluralRules.set(locale, rules);
+  return rules;
+};
+
+/**
+ * Picks the form a count calls for, by the rules of the locale the phrase came from.
+ *
+ * @returns The chosen form, or `other` for a category that locale has not written.
+ */
+const selectPlural = (
+  forms: PluralForms,
+  locale: string,
+  key: string,
+  values: ReadValues,
+): string => {
+  const count = values?.['count'];
+  if (typeof count !== 'number') {
+    throw new TypeError(`'${key}' has plural forms and needs a numeric 'count'`);
+  }
+  return forms[rulesFor(locale).select(count)] ?? forms.other;
+};
+
+/**
+ * Reads a wording in the locale asked for, falling back to English when that locale has
+ * no entry for it.
+ *
+ * @returns The wording, and the locale it actually came from.
+ */
+const readPhrase = (
+  phrases: LocaleTable[string],
+  key: string,
+  locale: string,
+): { phrase: Phrase; locale: string } => {
+  const written = phrases[locale];
+  if (written !== undefined) {
+    return { phrase: written, locale };
+  }
+
+  // The english wording the type requires can still be missing at runtime: a card can pass
+  // a table it built, and `i18n.test.ts` covers exactly that.
+  const english = phrases[FALLBACK_LOCALE];
+  // oxlint-disable-next-line typescript/no-unnecessary-condition
+  if (english === undefined) {
+    throw new Error(`'${key}' translation not found for locale '${locale}'`);
+  }
+  return { phrase: english, locale: FALLBACK_LOCALE };
+};
+
+/**
+ * Draws a key's wording: the locale's own if it has one and English otherwise, in the
+ * plural form its count calls for, with its `{name}` placeholders substituted.
+ *
+ * @returns The wording as the card draws it.
+ */
+const draw = (
+  phrases: LocaleTable[string],
+  key: string,
+  locale: string,
+  values: ReadValues,
+): string => {
+  const { phrase, locale: from } = readPhrase(phrases, key, locale);
+  const wording = typeof phrase === 'string' ? phrase : selectPlural(phrase, from, key, values);
+
+  return interpolate(wording, key, values);
+};
+
+/**
+ * A card's translations bound to one locale: each key a function of the values its own
+ * wording declares.
+ */
+type Localized<Table extends LocaleTable> = {
+  [Key in keyof Table]: (...args: ValuesArg<Table[Key]['en']>) => string;
+};
+
+/**
+ * Binds a card's translations to one locale, so a card names a wording where it draws it
+ * — `t.title({ login })` — rather than naming a key. That is what lets an editor follow a
+ * wording to where it is written, and why a key carries no card name in front of it.
+ *
+ * @returns One function per key the table declares.
+ */
+const localize = <Table extends LocaleTable>(table: Table, locale?: string): Localized<Table> => {
+  const asked = locale || FALLBACK_LOCALE;
+  const wordings: Record<string, (values?: ReadValues) => string> = {};
+
+  for (const [key, phrases] of Object.entries(table)) {
+    wordings[key] = (values): string => draw(phrases, key, asked, values);
+  }
+
+  // A mapped type over a table known only as a type parameter needs the assertion.
+  return wordings as Localized<Table>;
+};
+
+export { defineLocales, isLocaleAvailable, localize };
+export type { LocaleTable, Localized, Phrase };

package/src/common/render.ts

@@ -431,10 +431,15 @@ const renderError = ({
     theme,
   });
 
-  const hint =
+  /*
+   * Its own line, at the small size, because it no longer fits beside the title: the inherited URL
+   * ran to 561px inside a 576.5px card and this one reaches 587px. Measured in a canvas at the
+   * title's own font, so re-measure before putting it back on one line.
+   */
+  const report =
     UPSTREAM_API_ERRORS.has(secondaryMessage) || !show_repo_link
       ? ''
-      : ' file an issue at https://tinyurl.com/github-stats';
+      : 'File an issue at https://tinyurl.com/stats-forge-bug';
 
   return renderMarkup(
     el(
@@ -464,13 +469,15 @@ const renderError = ({
         fill: String(bgColor),
         stroke: borderColor,
       }),
-      el('text', { x: 25, y: 45, class: 'text' }, `Something went wrong!${hint}`),
+      el('text', { x: 25, y: 45, class: 'text' }, 'Something went wrong!'),
       el(
         'text',
         { 'data-testid': 'message', x: 25, y: 55, class: 'text small' },
         el('tspan', { x: 25, dy: 18 }, message),
         el('tspan', { x: 25, dy: 18, class: 'gray' }, secondaryMessage),
       ),
+      report !== '' &&
+        el('text', { 'data-testid': 'report', x: 25, y: 109, class: 'text small gray' }, report),
     ),
   );
 };

package/src/fetchers/index.ts

@@ -1,5 +1,6 @@
 export { fetchContributedTo } from './contributed-to.ts';
 export { fetchGist } from './gist.ts';
+export { fetchOrganization } from './organization.ts';
 export { fetchRepo } from './repo.ts';
 export { fetchRepoUserStats, fetchStats } from './stats.ts';
 export { fetchTopLanguages } from './top-languages.ts';
@@ -10,6 +11,7 @@ export type {
   ContributedToData,
   GistData,
   Lang,
+  OrganizationData,
   RepoUserStats,
   RepositoryData,
   StatsData,

package/src/fetchers/organization.ts

@@ -0,0 +1,153 @@
+import type { CardConfig } from '../common/config.ts';
+import { GITHUB_USERNAME_PATTERN } from '../common/constants.ts';
+import { CardError, ORGANIZATION_NOT_FOUND } from '../common/error.ts';
+import { createGraphQLFetcher } from '../common/http.ts';
+import type { GraphQLResponse } from '../common/http.ts';
+import { retryer } from '../common/retryer.ts';
+import { GetOrganizationDocument } from '../graphql/generated/organization.ts';
+import type {
+  GetOrganizationQuery,
+  OrgRepoInfoFragment,
+} from '../graphql/generated/organization.ts';
+
+import { graphqlError } from './graphql-error.ts';
+import type { OrganizationData } from './types.ts';
+
+const fetcher = createGraphQLFetcher(GetOrganizationDocument, 'token');
+
+const urlExample = '/api/org?org=ORG_NAME';
+
+const ORGANIZATION_ERROR =
+  'Something went wrong while trying to retrieve the organization data using the GraphQL API.';
+
+/**
+ * Pages of repositories the walk asks for, 100 each.
+ * Named in the doc comments below as the number it is, so the constant stays internal.
+ * The totals are sums over what it saw and the repositories arrive most-starred first,
+ * so the cap costs an organization past it the tail of its list rather than its headline figures.
+ */
+const MAX_REPO_PAGES = 5;
+
+/** The organization as the query returns it, once it has resolved. */
+type Organization = NonNullable<GetOrganizationQuery['organization']>;
+
+/**
+ * @returns The language most of those repositories name as their primary one, `null` when none do.
+ */
+const topLanguage = (
+  repos: Array<OrgRepoInfoFragment>,
+): { name: string; color: string | null } | null => {
+  const counts = new Map<string, { color: string | null; count: number }>();
+
+  for (const { primaryLanguage } of repos) {
+    if (primaryLanguage) {
+      const seen = counts.get(primaryLanguage.name);
+      counts.set(primaryLanguage.name, {
+        color: primaryLanguage.color,
+        count: (seen?.count ?? 0) + 1,
+      });
+    }
+  }
+
+  let top: { name: string; color: string | null } | null = null;
+  let max = 0;
+  for (const [name, { color, count }] of counts) {
+    if (count > max) {
+      max = count;
+      top = { name, color };
+    }
+  }
+
+  return top;
+};
+
+/**
+ * Fetch an organization and the totals of its public repositories.
+ *
+ * Only public, non-fork repositories are counted, most-starred first,
+ * and at most five pages of 100 — `truncated` says when the walk stopped early.
+ *
+ * @returns The organization data.
+ */
+const fetchOrganization = async (
+  { org }: { org: string | undefined },
+  config: CardConfig,
+): Promise<OrganizationData> => {
+  if (!org) {
+    throw CardError.missingParam(['org'], urlExample);
+  }
+  // `./fetchers` is a public export, so the login is checked here as well as at the api boundary.
+  if (!GITHUB_USERNAME_PATTERN.test(org)) {
+    throw new CardError('Invalid organization provided.', {
+      code: 'invalid_param',
+      param: 'org',
+    });
+  }
+
+  const repos: Array<OrgRepoInfoFragment> = [];
+  let organization: Organization | undefined;
+  let after: string | null = null;
+  let pages = 0;
+
+  do {
+    // Annotated because the walk feeds its own cursor back in, which TypeScript reads as circular.
+    const res: GraphQLResponse<GetOrganizationQuery> = await retryer(
+      fetcher,
+      { login: org, after },
+      config,
+    );
+    if (res.data.errors) {
+      // A login that is a user, or nothing at all, answers NOT_FOUND — which `graphqlError`
+      // words for a user query, so this endpoint's own wording is thrown instead.
+      if (res.data.errors[0]?.type === 'NOT_FOUND') {
+        throw new CardError('Organization not found', {
+          code: 'not_found',
+          secondaryMessage: ORGANIZATION_NOT_FOUND,
+        });
+      }
+      throw graphqlError(res.data.errors, res.statusText, ORGANIZATION_ERROR);
+    }
+
+    organization = res.data.data.organization ?? undefined;
+    if (!organization) {
+      throw new CardError('Organization not found', {
+        code: 'not_found',
+        secondaryMessage: ORGANIZATION_NOT_FOUND,
+      });
+    }
+
+    repos.push(...(organization.repositories.nodes ?? []).filter((node) => node !== null));
+    const { hasNextPage, endCursor } = organization.repositories.pageInfo;
+    after = hasNextPage ? endCursor : null;
+    pages += 1;
+  } while (after !== null && pages < MAX_REPO_PAGES);
+
+  const sum = (count: (repo: OrgRepoInfoFragment) => number): number =>
+    repos.reduce((total, repo) => total + count(repo), 0);
+
+  return {
+    login: organization.login,
+    name: organization.name || organization.login,
+    description: organization.description,
+    createdAt: organization.createdAt,
+    publicRepos: organization.repositories.totalCount,
+    totalStars: sum((repo) => repo.stargazerCount),
+    totalForks: sum((repo) => repo.forkCount),
+    totalWatchers: sum((repo) => repo.watchers.totalCount),
+    openIssues: sum((repo) => repo.issues.totalCount),
+    openPRs: sum((repo) => repo.pullRequests.totalCount),
+    totalReleases: sum((repo) => repo.releases.totalCount),
+    // An empty repository has no default branch, and a branch pointing at a tag has no history.
+    totalCommits: sum((repo) => {
+      const target = repo.defaultBranchRef?.target;
+      return target !== null && target !== undefined && 'history' in target
+        ? target.history.totalCount
+        : 0;
+    }),
+    publicMembers: organization.membersWithRole.totalCount,
+    topLanguage: topLanguage(repos),
+    truncated: after !== null,
+  };
+};
+
+export { fetchOrganization };

package/src/fetchers/types.ts

@@ -33,6 +33,42 @@ export interface RepoUserStats {
 
 export type RepositoryData = RepoInfo & RepoUserStats;
 
+/**
+ * An organization, with its public repositories aggregated.
+ * Every total is summed over the repositories the walk saw — public, non-fork ones,
+ * most-starred first — so `truncated` says whether that was all of them.
+ */
+export interface OrganizationData {
+  login: string;
+  /** The organization's display name, or its login when it has none. */
+  name: string;
+  description: string | null;
+  /** When the organization was created, as GitHub's own ISO 8601 instant. */
+  createdAt: string;
+  /** Public, non-fork repositories: the whole count, whether or not the walk saw them all. */
+  publicRepos: number;
+  totalStars: number;
+  totalForks: number;
+  totalWatchers: number;
+  openIssues: number;
+  openPRs: number;
+  totalReleases: number;
+  /**
+   * Commits on the default branch of every repository counted: every author, merges included,
+   * and whatever history a repository was imported with.
+   */
+  totalCommits: number;
+  /**
+   * Members GitHub shows publicly.
+   * Membership is private by default, so this counts fewer people than the organization has.
+   */
+  publicMembers: number;
+  /** The language most of those repositories name as their primary one, `null` when none do. */
+  topLanguage: { name: string; color: string | null } | null;
+  /** Whether the repository walk stopped at its page cap, leaving the totals short. */
+  truncated: boolean;
+}
+
 export interface StatsData {
   name: string;
   totalPRs: number;

package/src/graphql/generated/organization.ts

@@ -0,0 +1,109 @@
+// 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 OrgRepoInfoFragment = {
+  stargazerCount: number;
+  forkCount: number;
+  primaryLanguage: { color: string | null; name: string } | null;
+  watchers: { totalCount: number };
+  issues: { totalCount: number };
+  pullRequests: { totalCount: number };
+  releases: { totalCount: number };
+  defaultBranchRef: {
+    target: { history: { totalCount: number } } | Record<PropertyKey, never> | null;
+  } | null;
+};
+
+export type GetOrganizationQueryVariables = Exact<{
+  login: string;
+  after?: string | null | undefined;
+}>;
+
+export type GetOrganizationQuery = {
+  organization: {
+    login: string;
+    name: string | null;
+    description: string | null;
+    createdAt: string;
+    membersWithRole: { totalCount: number };
+    repositories: {
+      totalCount: number;
+      pageInfo: { hasNextPage: boolean; endCursor: string | null };
+      nodes: Array<{
+        stargazerCount: number;
+        forkCount: number;
+        primaryLanguage: { color: string | null; name: string } | null;
+        watchers: { totalCount: number };
+        issues: { totalCount: number };
+        pullRequests: { totalCount: number };
+        releases: { totalCount: number };
+        defaultBranchRef: {
+          target: { history: { totalCount: number } } | Record<PropertyKey, never> | null;
+        } | null;
+      } | null> | null;
+    };
+  } | null;
+};
+
+export const GetOrganizationDocument = graphqlDocument<
+  GetOrganizationQuery,
+  GetOrganizationQueryVariables
+>(`
+query getOrganization($login: String!, $after: String) {
+  organization(login: $login) {
+    login
+    name
+    description
+    createdAt
+    membersWithRole {
+      totalCount
+    }
+    repositories(
+      first: 100
+      after: $after
+      privacy: PUBLIC
+      isFork: false
+      orderBy: {field: STARGAZERS, direction: DESC}
+    ) {
+      totalCount
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      nodes {
+        ...OrgRepoInfo
+      }
+    }
+  }
+}
+fragment OrgRepoInfo on Repository {
+  stargazerCount
+  forkCount
+  primaryLanguage {
+    color
+    name
+  }
+  watchers {
+    totalCount
+  }
+  issues(states: OPEN) {
+    totalCount
+  }
+  pullRequests(states: OPEN) {
+    totalCount
+  }
+  releases {
+    totalCount
+  }
+  defaultBranchRef {
+    target {
+      ... on Commit {
+        history {
+          totalCount
+        }
+      }
+    }
+  }
+}`);