@stats-organization/github-readme-stats-core 2.1.4 → 2.2.0

package/src/common/config.ts

@@ -9,7 +9,8 @@ interface Config {
   whitelist: Array<string> | undefined;
   gistWhitelist: Array<string> | undefined;
   excludeRepositories: Array<string>;
-  fetchMultiPageStars: string | undefined;
+  /** Max pages of starred repos to fetch; `Infinity` means every page, `1` only the first. */
+  fetchMultiPageStars: number;
   pats: Array<PersonalAccessToken>;
 }
 
@@ -17,11 +18,19 @@ interface Config {
  * @param value Comma-separated string.
  * @returns Parsed string values.
  */
-const parseCsv = (value: string | undefined): Array<string> | undefined => {
-  if (!value) {
-    return undefined;
+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 => {
+  if (value === "true") {
+    return Infinity;
   }
-  return value.split(",");
+  const limit = Number(value);
+  return limit > 0 ? limit : 1;
 };
 
 /**
@@ -45,37 +54,21 @@ const getDefaultEnv = (): Env => {
   return processEnv ?? {};
 };
 
-/**
- * @param config (Partial) config values to normalize.
- * @returns Normalized config object with defaults applied.
- */
-const normalizeConfig = (config: Partial<Config> = {}): Config => {
-  return {
-    whitelist: config.whitelist,
-    gistWhitelist: config.gistWhitelist,
-    excludeRepositories: config.excludeRepositories ?? [],
-    fetchMultiPageStars: config.fetchMultiPageStars,
-    pats: config.pats ?? [],
-  };
-};
-
 let currentConfig: Config;
 
 /**
  * @param env Environment variables used to build the runtime config.
  */
 export const loadConfigFromEnv = (env: Env = getDefaultEnv()): void => {
-  const whitelist = parseCsv(env["WHITELIST"]);
-  const gistWhitelist = parseCsv(env["GIST_WHITELIST"]);
-  const excludeRepositories = parseCsv(env["EXCLUDE_REPO"]) ?? [];
-
-  currentConfig = normalizeConfig({
-    whitelist,
-    gistWhitelist,
-    excludeRepositories,
-    fetchMultiPageStars: env["FETCH_MULTI_PAGE_STARS"],
+  currentConfig = {
+    whitelist: parseCsv(env["WHITELIST"]),
+    gistWhitelist: parseCsv(env["GIST_WHITELIST"]),
+    excludeRepositories: parseCsv(env["EXCLUDE_REPO"]) ?? [],
+    fetchMultiPageStars: parseFetchMultiPageStars(
+      env["FETCH_MULTI_PAGE_STARS"],
+    ),
     pats: parsePATsFromEnv(env),
-  });
+  };
 };
 
 loadConfigFromEnv();

package/src/common/constants.ts

@@ -1,7 +1,9 @@
+import type { RepositoryAffiliation } from "../graphql/generated/common.js";
+
 /**
  * Valid owner affiliations for GitHub API queries.
  */
-const OWNER_AFFILIATIONS: Array<string> = [
+const OWNER_AFFILIATIONS: Array<RepositoryAffiliation> = [
   "OWNER",
   "COLLABORATOR",
   "ORGANIZATION_MEMBER",

package/src/common/date.ts

@@ -0,0 +1,45 @@
+/** A span between two dates, as GitHub's range arguments take it. */
+interface GitHubDateRange {
+  /** Start of the range, inclusive. */
+  from: Date;
+  /** End of the range, inclusive. */
+  to: Date;
+}
+
+/**
+ * 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 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 => ({
+  from: new Date(Date.UTC(year, 0, 1)),
+  to: new Date(Date.UTC(year, 11, 31, 23, 59, 59)),
+});
+
+/**
+ * Get diff in minutes between two dates.
+ *
+ * @param d1 First date.
+ * @param d2 Second date.
+ * @returns Number of minutes between the two dates.
+ */
+const dateDiff = (d1: Date, d2: Date): number =>
+  Math.round((d1.getTime() - d2.getTime()) / (1000 * 60));
+
+export { dateDiff, getGitHubYearRange, toGitHubDateTime };
+export type { GitHubDateRange };

package/src/common/html.ts

@@ -6,7 +6,7 @@
 const encodeHTML = (str: string): string => {
   return (
     str
-      .replace(/[\u00A0-\u9999<>&](?!#)/gim, (i: string) => {
+      .replace(/[\u00A0-\u9999<>&"'](?!#)/gim, (i: string) => {
         return `&#${i.charCodeAt(0)};`;
       })
       // eslint-disable-next-line no-control-regex

package/src/common/http.ts

@@ -0,0 +1,71 @@
+import axios from "axios";
+import type { AxiosRequestConfig, AxiosResponse } from "axios";
+
+import type { GraphQLDocument } from "../graphql/graphqlDocument.js";
+
+const GITHUB_GRAPHQL_API = "https://api.github.com/graphql";
+
+/** Response of a GraphQL call: the envelope the GitHub API wraps results in. */
+type GraphQLResponse<TResult> = AxiosResponse<{
+  data: TResult;
+  errors?: Array<{ type?: string; message?: string }>;
+}>;
+
+/**
+ * @param document Generated query document.
+ * @param scheme `Authorization` scheme for the token.
+ * @returns A fetcher `retryer` can drive.
+ */
+const createGraphQLFetcher = <TResult, TVariables>(
+  document: GraphQLDocument<TResult, TVariables>,
+  scheme: "bearer" | "token",
+) => {
+  return (
+    variables: TVariables,
+    token: string,
+  ): Promise<GraphQLResponse<TResult>> => {
+    return axios({
+      url: GITHUB_GRAPHQL_API,
+      method: "post",
+      headers: { Authorization: `${scheme} ${token}` },
+      data: { query: document.text, variables },
+    });
+  };
+};
+
+/** Body of a GraphQL request sent to the GitHub API. */
+interface GraphQLRequest {
+  /** The GraphQL query. */
+  query: string;
+  /** Variables referenced by the query. */
+  variables: Record<string, unknown>;
+}
+
+/**
+ * Send an untyped GraphQL request to the GitHub API.
+ *
+ * @param data Request data.
+ * @param headers Request headers.
+ * @returns Request response.
+ *
+ * @description Superseded by {@link createGraphQLFetcher}.
+ * Still used by the backend status endpoints for their own `rateLimit` query,
+ * and part of this package's published API.
+ *
+ * @todo consider dropping this once those endpoints post through axios directly,
+ * which they already depend on.
+ */
+const request = (
+  data: GraphQLRequest,
+  headers: NonNullable<AxiosRequestConfig["headers"]>,
+): Promise<AxiosResponse> => {
+  return axios({
+    url: GITHUB_GRAPHQL_API,
+    method: "post",
+    headers,
+    data,
+  });
+};
+
+export { createGraphQLFetcher, request };
+export type { GraphQLResponse };

package/src/common/icons.ts

@@ -38,6 +38,7 @@ const icons = {
   discussions_started: `<path fill-rule="evenodd" d="M1.75 1h8.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 10.25 10H7.061l-2.574 2.573A1.458 1.458 0 0 1 2 11.543V10h-.25A1.75 1.75 0 0 1 0 8.25v-5.5C0 1.784.784 1 1.75 1ZM1.5 2.75v5.5c0 .138.112.25.25.25h1a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h3.5a.25.25 0 0 0 .25-.25v-5.5a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13 2a.25.25 0 0 0-.25-.25h-.5a.75.75 0 0 1 0-1.5h.5c.966 0 1.75.784 1.75 1.75v5.5A1.75 1.75 0 0 1 14.25 12H14v1.543a1.458 1.458 0 0 1-2.487 1.03L9.22 12.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.22 2.22v-2.19a.75.75 0 0 1 .75-.75h1a.25.25 0 0 0 .25-.25Z" />`,
   discussions_answered: `<path fill-rule="evenodd" d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z" />`,
   comments: `<path d="M1 2.75C1 1.784 1.784 1 2.75 1h10.5c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 13.25 12H9.06l-2.573 2.573A1.458 1.458 0 0 1 4 13.543V12H2.75A1.75 1.75 0 0 1 1 10.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h4.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z" />`,
+  contributions: `<path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm7.25-3.25v2.5h2.5a.75.75 0 0 1 0 1.5h-2.5v2.5a.75.75 0 0 1-1.5 0v-2.5h-2.5a.75.75 0 0 1 0-1.5h2.5v-2.5a.75.75 0 0 1 1.5 0Z"/>`,
   gist: `<path fill-rule="evenodd" d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v12.5A1.75 1.75 0 0 1 14.25 16H1.75A1.75 1.75 0 0 1 0 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25V1.75a.25.25 0 0 0-.25-.25Zm7.47 3.97a.75.75 0 0 1 1.06 0l2 2a.75.75 0 0 1 0 1.06l-2 2a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L10.69 8 9.22 6.53a.75.75 0 0 1 0-1.06ZM6.78 6.53 5.31 8l1.47 1.47a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215l-2-2a.75.75 0 0 1 0-1.06l2-2a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042Z" />`,
 };
 

package/src/common/languageColors.json

@@ -44,6 +44,7 @@
   "Awk": "#c30e9b",
   "B (Formal Method)": "#8aa8c5",
   "B4X": "#00e4ff",
+  "BAML": "#a855f7",
   "BASIC": "#ff0000",
   "BQN": "#2b7067",
   "Ballerina": "#FF5000",
@@ -58,6 +59,7 @@
   "Blade": "#f7523f",
   "BlitzBasic": "#00FFAE",
   "BlitzMax": "#cd6400",
+  "Blueprint": "#3584E4",
   "Bluespec": "#12223c",
   "Bluespec BH": "#12223c",
   "Boo": "#d4bec1",
@@ -69,7 +71,7 @@
   "Bru": "#F4AA41",
   "BuildStream": "#006bff",
   "C": "#555555",
-  "C#": "#178600",
+  "C#": "#7355dd",
   "C++": "#f34b7d",
   "C3": "#2563eb",
   "CAP CDS": "#0092d1",
@@ -210,6 +212,7 @@
   "Glimmer JS": "#F5835F",
   "Glimmer TS": "#3178c6",
   "Glyph": "#c1ac7f",
+  "Gno": "#226c57",
   "Gnuplot": "#f0a9f0",
   "Go": "#00ADD8",
   "Go Checksums": "#00ADD8",
@@ -227,6 +230,7 @@
   "Graphviz (DOT)": "#2596be",
   "Groovy": "#4298b8",
   "Groovy Server Pages": "#4298b8",
+  "GtkRC": "#7fe719",
   "HAProxy": "#106da9",
   "HCL": "#844FBA",
   "HIP": "#4F3A4F",
@@ -416,6 +420,7 @@
   "OpenSCAD": "#e5cd45",
   "Option List": "#476732",
   "Org": "#77aa99",
+  "OverPy": "#78b355",
   "OverpassQL": "#cce2aa",
   "Oxygene": "#cdd0e3",
   "Oz": "#fab738",
@@ -445,10 +450,12 @@
   "Portugol": "#f8bd00",
   "PostCSS": "#dc3a0c",
   "PostScript": "#da291c",
+  "Power Query": "#d38e0d",
   "PowerBuilder": "#8f0f8d",
   "PowerShell": "#012456",
   "Praat": "#c8506d",
   "Prisma": "#0c344b",
+  "Pro*C": "#bb8368",
   "Processing": "#0096D8",
   "Procfile": "#3B2F63",
   "Prolog": "#74283c",
@@ -490,6 +497,7 @@
   "Rebol": "#358a5b",
   "Record Jar": "#0673ba",
   "Red": "#f50000",
+  "Redscript": "#f44336",
   "Regular Expression": "#009a00",
   "Ren'Py": "#ff7f7f",
   "Rez": "#FFDAB3",
@@ -659,6 +667,7 @@
   "nanorc": "#2d004d",
   "nesC": "#94B0C7",
   "ooc": "#b0b77e",
+  "pkg-config": "#2b5e82",
   "q": "#0040cd",
   "reStructuredText": "#141414",
   "sed": "#64b970",

package/src/common/languageColors.ts

@@ -0,0 +1,19 @@
+import languageColorsJson from "./languageColors.json" with { type: "json" };
+
+/** Shown for languages missing from the generated table, and for a null API color. */
+const DEFAULT_LANG_COLOR = "#858585";
+
+// The generated JSON types has literal keys; index it as a plain lookup table.
+const languageColors: Record<string, string> = languageColorsJson;
+
+/**
+ * Resolves a language's brand color from the generated table.
+ *
+ * @param name Language name as GitHub spells it.
+ * @returns The language's hex color, or the default gray when it is unknown.
+ */
+const getLanguageColor = (name: string): string => {
+  return languageColors[name] ?? DEFAULT_LANG_COLOR;
+};
+
+export { DEFAULT_LANG_COLOR, getLanguageColor };

package/src/common/ops.ts

@@ -0,0 +1,158 @@
+import toEmoji from "emoji-name-map";
+
+import type { RepositoryAffiliation } from "../graphql/generated/common.js";
+
+import { OWNER_AFFILIATIONS } from "./constants.js";
+import { CustomError } from "./error.js";
+
+/**
+ * Returns boolean if value is either "true" or "false" else the value as it is.
+ *
+ * @param value The value to parse.
+ * @returns The parsed value.
+ */
+const parseBoolean = (value: string | boolean): boolean | undefined => {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    if (value.toLowerCase() === "true") {
+      return true;
+    } else if (value.toLowerCase() === "false") {
+      return false;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Parse string to array of strings.
+ *
+ * @param str The string to parse.
+ * @returns The array of strings.
+ */
+const parseArray = (str: string): Array<string> => {
+  if (!str) {
+    return [];
+  }
+  return str.split(",");
+};
+
+/**
+ * Clamp the given number between the given range.
+ *
+ * @param number The number to clamp.
+ * @param min The minimum value.
+ * @param max The maximum value.
+ * @returns The clamped number.
+ */
+const clampValue = (
+  number: string | number,
+  min: number,
+  max: number,
+): number => {
+  if (Number.isNaN(parseInt(String(number), 10))) {
+    return min;
+  }
+  return Math.max(min, Math.min(Number(number), max));
+};
+
+/**
+ * Lowercase and trim string.
+ *
+ * @param name String to lowercase and trim.
+ * @returns Lowercased and trimmed string.
+ */
+const lowercaseTrim = (name: string): string => name.toLowerCase().trim();
+
+/**
+ * Split array of languages in two columns.
+ *
+ * @template T Language object.
+ * @param arr Array of languages.
+ * @param perChunk Number of languages per column.
+ * @returns Array of languages split in two columns.
+ */
+const chunkArray = <T>(arr: Array<T>, perChunk: number): Array<Array<T>> => {
+  return arr.reduce<Array<Array<T>>>((resultArray, item, index) => {
+    const chunkIndex = Math.floor(index / perChunk);
+    const chunk = resultArray[chunkIndex] ?? [];
+    chunk.push(item);
+    resultArray[chunkIndex] = chunk;
+    return resultArray;
+  }, []);
+};
+
+/**
+ * Parse emoji from string.
+ *
+ * @param str String to parse emoji from.
+ * @returns String with emoji parsed.
+ */
+const parseEmojis = (str: string): string => {
+  if (!str) {
+    throw new Error("[parseEmoji]: str argument not provided");
+  }
+  return str.replace(/:\w+:/gm, (emoji) => {
+    return toEmoji.get(emoji) || "";
+  });
+};
+
+const isOwnerAffiliation = (value: string): value is RepositoryAffiliation =>
+  OWNER_AFFILIATIONS.some((affiliation) => affiliation === value);
+
+/**
+ * Parse owner affiliations.
+ *
+ * @param affiliations input affiliations to be parsed.
+ * @returns Parsed affiliations.
+ *
+ * @throws {CustomError} If affiliations contains invalid values.
+ */
+const parseOwnerAffiliations = (
+  affiliations: Array<string>,
+): Array<RepositoryAffiliation> => {
+  // Set default value for ownerAffiliations.
+  // NOTE: Done here since parseArray() will always return an empty array even nothing
+  //was specified.
+  const normalized =
+    affiliations.length > 0
+      ? affiliations.map((affiliation) => affiliation.toUpperCase())
+      : ["OWNER"];
+
+  // Check if ownerAffiliations contains valid values.
+  if (!normalized.every(isOwnerAffiliation)) {
+    throw new CustomError(
+      "Invalid query parameter",
+      CustomError.INVALID_AFFILIATION,
+    );
+  }
+  return normalized;
+};
+
+const buildSearchFilter = (
+  repos: Array<string> | string = [],
+  owners: Array<string> | string = [],
+): string => {
+  const repoFilter =
+    Array.isArray(repos) && repos.length > 0
+      ? repos.map((r) => `repo:${r} `).join("")
+      : "";
+  const orgFilter =
+    Array.isArray(owners) && owners.length > 0
+      ? owners.map((o) => `owner:${o} `).join("")
+      : "";
+  return repoFilter + orgFilter;
+};
+
+export {
+  parseBoolean,
+  parseArray,
+  clampValue,
+  lowercaseTrim,
+  chunkArray,
+  parseEmojis,
+  parseOwnerAffiliations,
+  buildSearchFilter,
+};