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

package/src/common/color.ts

@@ -1,38 +1,33 @@
-import { isThemeName, themes } from '../themes/index.js';
+import { isThemeName, themes } from '../themes/index.ts';
 
 /** Matches a 3-, 4-, 6-, or 8-digit hex color with no leading `#`. */
-const HEX_COLOR = /^([A-Fa-f0-9]{8}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{3})$/;
+const HEX_COLOR = /^(?<digits>[A-Fa-f0-9]{8}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{3})$/;
 
 /**
  * Checks if a value is a bare hex color, i.e. hex digits with no `#` prefix
  * (`"f00"`, `"ffffff"`). This is the form user-supplied color params and
  * gradient stops arrive in.
  *
- * @param value Value to check.
  * @returns True if the value is a bare hex color.
  */
-const isBareHexColor = (value: unknown): boolean => {
-  return typeof value === 'string' && HEX_COLOR.test(value);
-};
+const isBareHexColor = (value: unknown): boolean =>
+  typeof value === 'string' && HEX_COLOR.test(value);
 
 /**
  * Checks if a value is a `#`-prefixed hex color (`"#f00"`, `"#ffffff"`). This
  * is the form colors take once resolved by {@link getCardColors}, i.e. right
  * before they are written into the SVG.
  *
- * @param value Value to check.
  * @returns True if the value is a `#`-prefixed hex color.
  */
-const isPrefixedHexColor = (value: unknown): boolean => {
-  return typeof value === 'string' && value.startsWith('#') && HEX_COLOR.test(value.slice(1));
-};
+const isPrefixedHexColor = (value: unknown): boolean =>
+  typeof value === 'string' && value.startsWith('#') && HEX_COLOR.test(value.slice(1));
 
 /**
  * Checks if the given parts form a valid gradient: a finite numeric angle
  * followed by at least two bare-hex color stops, e.g. `["90", "f00", "0f0"]`.
  * The angle is written into the SVG `gradientTransform="rotate(...)"`.
  *
- * @param parts Gradient parts: `[angle, ...stops]`.
  * @returns True if the parts form a valid gradient.
  */
 const isValidGradient = (parts: Array<string>): boolean => {
@@ -42,14 +37,13 @@ const isValidGradient = (parts: Array<string>): boolean => {
     angle !== undefined &&
     angle.trim() !== '' &&
     Number.isFinite(Number(angle)) &&
-    stops.every(isBareHexColor)
+    stops.every((stop) => isBareHexColor(stop))
   );
 };
 
 /**
  * Checks if a string is a valid input for a color or gradient.
  *
- * @param color String to check, may be null or undefined.
  * @returns True if the given string is a valid input.
  */
 const isValidColorInput = (color: string | null | undefined): boolean => {
@@ -62,13 +56,11 @@ const isValidColorInput = (color: string | null | undefined): boolean => {
 /**
  * Retrieves a gradient if color has more than one valid hex codes else a single color.
  *
- * @param color The color to parse.
- * @param fallbackColor The fallback color.
  * @returns The gradient or color.
  */
 const fallbackColor = (
   color: string | undefined,
-  fallbackColor: string | Array<string>,
+  fallback: string | Array<string>,
 ): string | Array<string> => {
   const colors = color ? color.split(',') : [];
   if (colors.length > 1 && isValidGradient(colors)) {
@@ -79,7 +71,46 @@ const fallbackColor = (
     return `#${color}`;
   }
 
-  return fallbackColor;
+  return fallback;
+};
+
+/** Border a light background gets when neither the user nor the theme names one. */
+const LIGHT_BG_BORDER = '#0000001f';
+/** Border a dark background gets when neither the user nor the theme names one. */
+const DARK_BG_BORDER = '#ffffff26';
+/** Border a see-through background gets: neutral, since the page behind it decides the contrast. */
+const TRANSLUCENT_BG_BORDER = '#8b949e59';
+
+/**
+ * @returns Its `[r, g, b, a]` channels, each on 0–1.
+ */
+const hexChannels = (hex: string): [number, number, number, number] => {
+  const digits = hex.slice(1);
+  const expanded = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join('') : digits;
+  const channel = (index: number): number =>
+    Number.parseInt(expanded.slice(index * 2, index * 2 + 2), 16) / 255;
+
+  return [channel(0), channel(1), channel(2), expanded.length === 8 ? channel(3) : 1];
+};
+
+/**
+ * Derives a border from the background, so a dark card never gets a light hairline.
+ *
+ * @returns A translucent `#`-prefixed hex border color.
+ */
+const borderColorFor = (bgColor: string | Array<string>): string => {
+  // A gradient is judged by its first stop.
+  const hex = typeof bgColor === 'string' ? bgColor : `#${bgColor[1] ?? ''}`;
+  if (!isPrefixedHexColor(hex)) {
+    return LIGHT_BG_BORDER;
+  }
+
+  const [r, g, b, a] = hexChannels(hex);
+  if (a < 0.5) {
+    return TRANSLUCENT_BG_BORDER;
+  }
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.5 ? DARK_BG_BORDER : LIGHT_BG_BORDER;
 };
 
 /**
@@ -134,15 +165,6 @@ type ColorInput = Partial<Record<BaseColorKey, string | undefined>>;
 /**
  * Returns theme based colors with proper overrides and defaults.
  *
- * @param props Function arguments.
- * @param props.title_color Card title color.
- * @param props.text_color Card text color.
- * @param props.icon_color Card icon color.
- * @param props.bg_color Card background color.
- * @param props.border_color Card border color.
- * @param props.ring_color Card ring color.
- * @param props.prog_bar_bg_color Progress bar background color.
- * @param props.theme Card theme.
  * @returns Card colors.
  */
 const getCardColors = ({
@@ -158,29 +180,24 @@ const getCardColors = ({
   const defaultTheme = themes.default;
   const selectedTheme = isThemeName(theme) ? themes[theme] : defaultTheme;
 
-  const defaultBorderColor =
-    'border_color' in selectedTheme ? selectedTheme.border_color : defaultTheme.border_color;
+  const themeBorderColor = 'border_color' in selectedTheme ? selectedTheme.border_color : undefined;
 
-  // get the color provided by the user else the theme color
-  // finally if both colors are invalid fallback to default theme
+  // Each color is the user's, else the selected theme's, else the default theme's.
   const titleColor = fallbackColor(
     title_color || selectedTheme.title_color,
-    '#' + defaultTheme.title_color,
+    `#${defaultTheme.title_color}`,
   );
-
-  // get the color provided by the user else the theme color
-  // finally if both colors are invalid we use the titleColor
   const iconColor = fallbackColor(
     icon_color || selectedTheme.icon_color,
-    '#' + defaultTheme.icon_color,
+    `#${defaultTheme.icon_color}`,
   );
   const textColor = fallbackColor(
     text_color || selectedTheme.text_color,
-    '#' + defaultTheme.text_color,
+    `#${defaultTheme.text_color}`,
   );
-  const bgColor = fallbackColor(bg_color || selectedTheme.bg_color, '#' + defaultTheme.bg_color);
+  const bgColor = fallbackColor(bg_color || selectedTheme.bg_color, `#${defaultTheme.bg_color}`);
 
-  const borderColor = fallbackColor(border_color || defaultBorderColor, '#' + defaultBorderColor);
+  const borderColor = fallbackColor(border_color || themeBorderColor, borderColorFor(bgColor));
   // No theme defines `ring_color`, so it falls back to the title color.
   const ringColor = fallbackColor(ring_color, titleColor);
   // No theme defines `prog_bar_bg_color`, so it falls back to "#ddd".
@@ -194,7 +211,7 @@ const getCardColors = ({
     typeof iconColor !== 'string' ||
     typeof borderColor !== 'string'
   ) {
-    throw new Error('Unexpected behavior, all colors except background should be string.');
+    throw new TypeError('Unexpected behavior, all colors except background should be string.');
   }
 
   return {
@@ -214,14 +231,29 @@ type LightDarkColorParams = Partial<Record<`${BaseColorKey}_${ThemeVariant}`, st
  * Returns the light- or dark-mode-specific color params, given a set of
  * raw query params. Also removes the "_light" or "_dark" suffixes.
  *
- * @param params Raw query params with optional `_light` / `_dark` suffixes.
- * @param suffix `"_light"` or `"_dark"`.
  * @returns ColorInput with the suffix stripped, ready for `getCardColors`.
  */
 const extractLightDarkColors = (
   params: LightDarkColorParams,
   suffix: `_${ThemeVariant}`,
-): ColorInput => Object.fromEntries(BASE_COLOR_KEYS.map((key) => [key, params[`${key}${suffix}`]]));
+): ColorInput => {
+  const colors: ColorInput = {};
+  for (const key of BASE_COLOR_KEYS) {
+    const value = params[`${key}${suffix}`];
+    if (value !== undefined) {
+      colors[key] = value;
+    }
+  }
+  return colors;
+};
+
+/**
+ * Every suffixed key, so asking "any per-scheme colors at all?" is one pass over names,
+ * not two objects built to be thrown away.
+ */
+const MODE_OVERRIDE_KEYS: ReadonlyArray<keyof LightDarkColorParams> = THEME_VARIANTS.flatMap(
+  (variant) => BASE_COLOR_KEYS.map((key) => `${key}_${variant}` as const),
+);
 
 /**
  * Returns resolved colors for both light and dark mode given all input params.
@@ -234,31 +266,22 @@ const extractLightDarkColors = (
  * Anything a mode does not override falls back to the general params,
  * so a partial override such as `bg_color_dark` alone keeps every other color from the base theme.
  *
- * When no `_light` / `_dark` param is provided at all, `darkColors` is `null` and the caller emits no dark-mode block.
+ * When no `_light` / `_dark` param is provided at all,
+ * `darkColors` is `null` and the caller emits no dark-mode block.
  *
- * @param params Raw query params, containing both general and `_light`/`_dark` suffixed colors and themes.
  * @returns `{ lightColors, darkColors }`, resolved colors for both light and dark mode
  */
 const getLightDarkColors = (
   params: ColorInput & LightDarkColorParams,
 ): { lightColors: CardColors; darkColors: CardColors | null } => {
-  const lightOverrides = extractLightDarkColors(params, '_light');
-  const darkOverrides = extractLightDarkColors(params, '_dark');
-
-  const hasModeOverrides =
-    Object.values(lightOverrides).some((v) => v !== undefined) ||
-    Object.values(darkOverrides).some((v) => v !== undefined);
-
-  if (!hasModeOverrides) {
+  // The common case is no per-scheme params at all, so it never builds the overrides.
+  if (!MODE_OVERRIDE_KEYS.some((key) => params[key] !== undefined)) {
     return { lightColors: getCardColors(params), darkColors: null };
   }
 
-  const defined = (obj: ColorInput): ColorInput =>
-    Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
-
   return {
-    lightColors: getCardColors({ ...params, ...defined(lightOverrides) }),
-    darkColors: getCardColors({ ...params, ...defined(darkOverrides) }),
+    lightColors: getCardColors({ ...params, ...extractLightDarkColors(params, '_light') }),
+    darkColors: getCardColors({ ...params, ...extractLightDarkColors(params, '_dark') }),
   };
 };
 

package/src/common/config.ts

@@ -1,5 +1,5 @@
-import { defaultFetch } from './http.js';
-import type { FetchLike } from './http.js';
+import { defaultFetch } from './http.ts';
+import type { FetchLike } from './http.ts';
 
 type Env = Record<string, string | undefined>;
 
@@ -20,14 +20,12 @@ interface CardConfigInit {
 }
 
 /**
- * @param value Comma-separated string.
  * @returns Parsed string values.
  */
 const parseCsv = (value: string | undefined): Array<string> | undefined =>
   value ? value.split(',') : undefined;
 
 /**
- * @param value Raw `FETCH_MULTI_PAGE_STARS` value.
  * @returns Page limit: `"true"` means every page, a positive number caps the pages, anything else means one.
  */
 const parseFetchMultiPageStars = (value: string | undefined): number => {
@@ -39,7 +37,6 @@ const parseFetchMultiPageStars = (value: string | undefined): number => {
 };
 
 /**
- * @param env Environment variables to inspect.
  * @returns Personal access tokens found in the environment.
  */
 const parsePATsFromEnv = (env: Env): Array<PersonalAccessToken> =>
@@ -74,10 +71,7 @@ export class CardConfig {
     this.fetch = init.fetch ?? defaultFetch;
   }
 
-  /**
-   * @param env Environment variables to read — the host passes `process.env` or an equivalent.
-   * @returns Config for this deployment.
-   */
+  /** @returns Config for this deployment. */
   static fromEnv(env: Env): CardConfig {
     return new CardConfig({
       pats: parsePATsFromEnv(env),
@@ -88,20 +82,13 @@ export class CardConfig {
     });
   }
 
-  /**
-   * @param id Username or gist id being requested.
-   * @param kind Which allowlist applies.
-   * @returns Whether this deployment serves the id.
-   */
+  /** @returns Whether this deployment serves the id. */
   isAllowed(id: string, kind: 'username' | 'gist'): boolean {
     const list = kind === 'gist' ? this.gistAllowlist : this.usernameAllowlist;
     return list === undefined || list.includes(id);
   }
 
-  /**
-   * @param overrides Fields to replace.
-   * @returns A copy with `overrides` applied — how a host swaps in a user's PAT per request.
-   */
+  /** @returns A copy with `overrides` applied — how a host swaps in a user's PAT per request. */
   with(overrides: CardConfigInit): CardConfig {
     return new CardConfig({
       pats: this.pats,

package/src/common/constants.ts

@@ -1,4 +1,10 @@
-import type { RepositoryAffiliation } from '../graphql/generated/common.js';
+import type { RepositoryAffiliation } from '../graphql/generated/common.ts';
+
+/** The year GitHub launched, and so the earliest one a card can be asked to count from. */
+const GITHUB_EPOCH_YEAR = 2008;
+
+/** A GitHub login: alphanumerics and single inner hyphens, 39 characters at most. */
+const GITHUB_USERNAME_PATTERN = /^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i;
 
 /**
  * Valid owner affiliations for GitHub API queries.
@@ -9,4 +15,4 @@ const OWNER_AFFILIATIONS: Array<RepositoryAffiliation> = [
   'ORGANIZATION_MEMBER',
 ];
 
-export { OWNER_AFFILIATIONS };
+export { GITHUB_EPOCH_YEAR, GITHUB_USERNAME_PATTERN, OWNER_AFFILIATIONS };

package/src/common/date.ts

@@ -1,4 +1,8 @@
-/** A span between two dates, as GitHub's range arguments take it. */
+/** @file A range reaches GitHub one calendar year at a time; `contributionsCollection` refuses a longer one. */
+
+import { GITHUB_EPOCH_YEAR } from './constants.ts';
+
+/** A range between two dates, as GitHub's range arguments take it. */
 interface GitHubDateRange {
   /** Start of the range, inclusive. */
   from: Date;
@@ -6,23 +10,24 @@ interface GitHubDateRange {
   to: Date;
 }
 
+/** A year, a year and month, or a full date. */
+const RANGE_DATE_PATTERN = /^(?<year>\d{4})(?:-(?<month>\d{2})(?:-(?<day>\d{2}))?)?$/;
+
 /**
  * Format a date as a GitHub `DateTime` scalar.
  * Seconds precision, no milliseconds.
  *
- * @param date Date to format.
  * @returns e.g. `2024-01-01T00:00:00Z`.
  */
 const toGitHubDateTime = (date: Date): string => `${date.toISOString().slice(0, 19)}Z`;
 
 /**
- * The full UTC span of a calendar year, both ends inclusive.
+ * The full UTC range of a calendar year, both ends inclusive.
  *
  * The end matters to callers that would otherwise leave a range open:
  * GitHub's `contributionsCollection` defaults `to` to one year after `from`,
  * which pulls the next 1st of January into the year.
  *
- * @param year Four-digit year.
  * @returns The range covering it.
  */
 const getGitHubYearRange = (year: number): GitHubDateRange => ({
@@ -30,5 +35,130 @@ const getGitHubYearRange = (year: number): GitHubDateRange => ({
   to: new Date(Date.UTC(year, 11, 31, 23, 59, 59)),
 });
 
-export { getGitHubYearRange, toGitHubDateTime };
+/**
+ * The widest range a card can be asked for: GitHub's first year through the end of this one.
+ * The far end is the end of the year, not today, because a bare `to=2026` widens to its 31st of December.
+ *
+ * @returns The range, in UTC.
+ */
+const getWidestRange = (): GitHubDateRange => ({
+  from: getGitHubYearRange(GITHUB_EPOCH_YEAR).from,
+  to: getGitHubYearRange(new Date().getUTCFullYear()).to,
+});
+
+/**
+ * The range a card counts within, from the ends the query named.
+ *
+ * @returns The range, each open end filled from {@link getWidestRange}.
+ */
+const toRange = (from: Date | undefined, to: Date | undefined): GitHubDateRange => {
+  const widest = getWidestRange();
+  return { from: from ?? widest.from, to: to ?? widest.to };
+};
+
+/**
+ * Read one end of a range, written as `2024`, `2024-03` or `2024-03-15`.
+ * A partial date covers the whole of what it names, so `2024` starts on the 1st of January
+ * and ends on the 31st of December.
+ *
+ * @returns The instant, or `undefined` when the text does not name a date that exists.
+ */
+const parseRangeDate = (value: string, end: 'from' | 'to'): Date | undefined => {
+  const match = RANGE_DATE_PATTERN.exec(value);
+  if (!match) {
+    return undefined;
+  }
+
+  const { year: yearText, month: monthText, day: dayText } = match.groups ?? {};
+  const year = Number(yearText);
+  const month = monthText === undefined ? 1 : Number(monthText);
+  const day = dayText === undefined ? 1 : Number(dayText);
+
+  const start = new Date(Date.UTC(year, month - 1, day));
+  // Date.UTC rolls an impossible date forward rather than refusing it
+  if (start.getUTCMonth() + 1 !== month || start.getUTCDate() !== day) {
+    return undefined;
+  }
+  if (end === 'from') {
+    return start;
+  }
+
+  const nextUnit =
+    dayText !== undefined
+      ? Date.UTC(year, month - 1, day + 1)
+      : monthText !== undefined
+        ? Date.UTC(year, month, 1)
+        : Date.UTC(year + 1, 0, 1);
+  return new Date(nextUnit - 1000);
+};
+
+/**
+ * Split a range into one per calendar year, each clipped to it.
+ *
+ * @returns Them, oldest first; empty when the range is inverted.
+ */
+const toYearRanges = ({ from, to }: GitHubDateRange): Array<GitHubDateRange> => {
+  const ranges: Array<GitHubDateRange> = [];
+  for (let year = from.getUTCFullYear(); year <= to.getUTCFullYear(); year += 1) {
+    const yearRange = getGitHubYearRange(year);
+    const start = from > yearRange.from ? from : yearRange.from;
+    const end = to < yearRange.to ? to : yearRange.to;
+    if (start <= end) {
+      ranges.push({ from: start, to: end });
+    }
+  }
+  return ranges;
+};
+
+/**
+ * Whole years as a card writes them.
+ *
+ * @returns e.g. `2024` or `2020–2024`.
+ */
+const formatYears = (first: number, last: number): string =>
+  first === last ? `${first}` : `${first}–${last}`;
+
+/**
+ * A range as a card writes it, at the coarsest granularity that stays true.
+ *
+ * @returns e.g. `2024`, `2020–2024` or `2024-03-15 – 2024-06-30`.
+ */
+const formatRange = ({ from, to }: GitHubDateRange): string => {
+  const firstYear = from.getUTCFullYear();
+  const lastYear = to.getUTCFullYear();
+  const wholeYears =
+    from.getTime() === getGitHubYearRange(firstYear).from.getTime() &&
+    to.getTime() === getGitHubYearRange(lastYear).to.getTime();
+
+  if (!wholeYears) {
+    return `${from.toISOString().slice(0, 10)} – ${to.toISOString().slice(0, 10)}`;
+  }
+  return formatYears(firstYear, lastYear);
+};
+
+/**
+ * The ranges a walk asks GitHub for: one per calendar year the account contributed in.
+ * Ordered here, which is what makes a walk's ties chronological.
+ *
+ * @returns Them, oldest first.
+ */
+const toContributionRanges = (
+  contributionYears: ReadonlyArray<number>,
+  range: GitHubDateRange,
+): Array<GitHubDateRange> => {
+  const contributed = new Set(contributionYears);
+  return toYearRanges(range).filter((year) => contributed.has(year.from.getUTCFullYear()));
+};
+
+export {
+  formatRange,
+  formatYears,
+  getWidestRange,
+  getGitHubYearRange,
+  parseRangeDate,
+  toContributionRanges,
+  toGitHubDateTime,
+  toRange,
+  toYearRanges,
+};
 export type { GitHubDateRange };