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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stats-forge/github-stats-forge-core",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "Dynamically generate stats for your GitHub readme",
   "keywords": [
     "card-generator",
@@ -43,7 +43,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/stats-forge/github-stats-forge.git",
+    "url": "git+https://github.com/stats-forge/github-stats-forge.git",
     "directory": "packages/core"
   },
   "files": [
@@ -52,20 +52,11 @@
     "README.md"
   ],
   "type": "module",
-  "main": "./build/index.js",
   "exports": {
-    ".": {
-      "@stats/source": "./src/index.ts",
-      "default": "./build/index.js"
-    },
     "./api": {
       "@stats/source": "./src/api/index.ts",
       "default": "./build/api/index.js"
     },
-    "./cards": {
-      "@stats/source": "./src/cards/index.ts",
-      "default": "./build/cards/index.js"
-    },
     "./fetchers": {
       "@stats/source": "./src/fetchers/index.ts",
       "default": "./build/fetchers/index.js"
@@ -79,36 +70,36 @@
     "access": "public"
   },
   "dependencies": {
-    "emoji-name-map": "^2.0.3",
-    "github-username-regex": "^1.0.0",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@graphql-codegen/core": "6.2.0",
     "@graphql-codegen/typescript": "6.1.0",
-    "@graphql-codegen/typescript-operations": "6.1.2",
+    "@graphql-codegen/typescript-operations": "6.1.6",
     "@octokit/graphql-schema": "15.26.1",
     "@testing-library/dom": "10.4.1",
-    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/jest-dom": "7.0.1",
+    "@types/node": "24.13.3",
     "@uppercod/css-to-object": "1.1.1",
-    "graphql": "16.11.0",
-    "js-yaml": "5.2.1",
-    "jsdom": "29.1.1",
-    "vitest": "4.1.10"
+    "graphql": "16.14.2",
+    "js-yaml": "5.4.1",
+    "jsdom": "30.0.1",
+    "vitest": "4.1.11"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^24 || >=26"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "lint:publish": "attw --pack . --profile node16 --ignore-rules cjs-resolves-to-esm && publint --strict",
     "test": "vitest",
     "test:update:snapshot": "vitest -u",
     "test:e2e": "vitest --config vitest.config.e2e.ts",
     "bench": "vitest bench --run --config vitest.config.bench.ts",
-    "lint": "eslint",
-    "typecheck": "tsc -p tsconfig.typecheck.json",
-    "generate-graphql-types": "node scripts/generate-graphql-types",
-    "check-graphql-types": "node scripts/generate-graphql-types --check",
-    "generate-language-colors": "node scripts/generate-language-colors"
+    "typecheck": "tsc -p tsconfig.typecheck.json && tsc -p tsconfig.scripts.json",
+    "generate-graphql-types": "node scripts/generate-graphql-types.ts",
+    "check-graphql-types": "node scripts/generate-graphql-types.ts --check",
+    "generate-language-colors": "node scripts/generate-language-colors.ts",
+    "generate-emoji-map": "node scripts/generate-emoji-map.ts"
   }
 }

package/src/api/api-result.ts

@@ -1,7 +1,7 @@
-import type { ColorParams } from '../common/color.js';
-import type { ErrorCode } from '../common/error.js';
-import { CardError } from '../common/error.js';
-import { renderError } from '../common/render.js';
+import type { ColorParams } from '../common/color.ts';
+import type { ErrorCode } from '../common/error.ts';
+import { CardError } from '../common/error.ts';
+import { renderError } from '../common/render.ts';
 
 /**
  * Why a card could not be rendered, in a form a host can act on.
@@ -37,14 +37,15 @@ export type ApiResult =
 
 /**
  * Turns anything a handler threw into the one shape it answers with.
+ * Anything that is not a `CardError` is treated as upstream's.
  *
- * @param err The failure.
- *        Anything that is not a `CardError` is treated as upstream's.
- * @param renderOptions Colors the error card is drawn with;
- *        omitted when it was a color that was rejected.
  * @returns The rendered error.
  */
-export const errorResult = (err: unknown, renderOptions?: ColorParams): ApiResult => {
+export const errorResult = (
+  err: unknown,
+  /** omitted when it was a color that was rejected, which cannot draw its own error card */
+  renderOptions?: ColorParams,
+): ApiResult => {
   const error = CardError.from(err);
 
   return {

package/src/api/contributed-to.ts

@@ -0,0 +1,84 @@
+import * as z from 'zod/mini';
+
+import { renderContributedToCard } from '../cards/contributed-to.ts';
+import { fetchContributedTo } from '../fetchers/contributed-to.ts';
+
+import { cardHandler } from './handler.ts';
+import {
+  booleanParam,
+  fromParam,
+  localeParam,
+  looseIntParam,
+  numberParam,
+  ORDERED_RANGE,
+  rawParam,
+  safeListParam,
+  toParam,
+  usernameParam,
+} from './params.ts';
+
+/** What the contributed-to endpoint accepts, on top of the shared color params. */
+const contributedToQuery = z
+  .object({
+    username: usernameParam,
+    locale: localeParam,
+    repos_count: looseIntParam,
+    include_own_repos: booleanParam,
+    exclude_repo: safeListParam,
+    from: fromParam,
+    to: toParam,
+    hide_years: booleanParam,
+    hide_title: booleanParam,
+    hide_border: booleanParam,
+    card_width: looseIntParam,
+    custom_title: rawParam,
+    border_radius: numberParam,
+    disable_animations: booleanParam,
+  })
+  .check(ORDERED_RANGE);
+
+/**
+ * Render the contributed-to card for a set of query params.
+ *
+ * @returns The rendered card, or a rendered error.
+ */
+export const contributedTo = cardHandler(
+  contributedToQuery,
+  async (
+    {
+      username,
+      locale,
+      repos_count,
+      include_own_repos,
+      exclude_repo,
+      from,
+      to,
+      hide_years,
+      hide_title,
+      hide_border,
+      card_width,
+      custom_title,
+      border_radius,
+      disable_animations,
+    },
+    colors,
+    config,
+  ) => {
+    const data = await fetchContributedTo(
+      { username, include_own_repos, repos_count, exclude_repo, from, to },
+      config,
+    );
+
+    return renderContributedToCard(data, {
+      ...colors,
+      locale,
+      hide_years,
+      hide_title,
+      hide_border,
+      card_width,
+      custom_title,
+      border_radius,
+      disable_animations,
+    });
+  },
+);

package/src/api/gist.ts

@@ -1,66 +1,42 @@
 import * as z from 'zod/mini';
 
-import { renderGistCard } from '../cards/gist.js';
-import type { CardConfig } from '../common/config.js';
-import { fetchGist } from '../fetchers/gist.js';
+import { renderGistCard } from '../cards/gist.ts';
+import { fetchGist } from '../fetchers/gist.ts';
 
-import type { ApiResult } from './api-result.js';
-import { errorResult } from './api-result.js';
-import type { ApiQuery } from './params.js';
-import { booleanParam, numberParam, parseColorParams, parseParams, safeParam } from './params.js';
+import { cardHandler } from './handler.ts';
+import { booleanParam, localeParam, numberParam, safeParam } from './params.ts';
 
 /** What the gist endpoint accepts, on top of the shared color params. */
 const gistQuery = z.object({
   id: safeParam,
+  locale: localeParam,
   border_radius: numberParam,
   show_owner: booleanParam,
   browser_rendering: booleanParam,
   hide_border: booleanParam,
 });
 
-/** The query this endpoint accepts, checked against the schema above. */
-type GistApiQuery = ApiQuery<typeof gistQuery>;
-
 /**
  * Render the gist card for a set of query params.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.id GitHub gist ID.
- * @param query.border_radius Card border radius.
- * @param query.show_owner Whether to show the gist owner.
- * @param query.browser_rendering Whether the browser wraps the description text.
- * @param query.hide_border Whether to hide the card border.
- * @param config Deployment config supplying the PAT pool.
  * @returns The rendered card, or a rendered error.
  */
-export const gist = async (query: GistApiQuery, 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 { id, border_radius, show_owner, browser_rendering, hide_border } = parseParams(
-      gistQuery,
-      query,
-    );
-
+export const gist = cardHandler(
+  gistQuery,
+  async (
+    { id, locale, border_radius, show_owner, browser_rendering, hide_border },
+    colors,
+    config,
+  ) => {
     const gistData = await fetchGist({ id }, config);
 
-    return {
-      status: 'success',
-      content: renderGistCard(gistData, {
-        ...colors,
-        border_radius,
-        show_owner,
-        browser_rendering,
-        hide_border,
-      }),
-    };
-  } catch (err) {
-    return errorResult(err, colors);
-  }
-};
+    return renderGistCard(gistData, {
+      ...colors,
+      locale,
+      border_radius,
+      show_owner,
+      browser_rendering,
+      hide_border,
+    });
+  },
+);

package/src/api/handler.ts

@@ -0,0 +1,42 @@
+import type * as z from 'zod/mini';
+
+import type { ColorParams } from '../common/color.ts';
+import type { CardConfig } from '../common/config.ts';
+
+import type { ApiResult } from './api-result.ts';
+import { errorResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
+import { parseColorParams, parseParams } from './params.ts';
+
+/**
+ * An endpoint: the schema it accepts, and what it draws from the parsed params.
+ *
+ * Colors parse first and on their own, because a rejected color cannot be used to draw its own error card.
+ * Parsing throws, fetching throws, and one `catch` turns whatever was thrown into the answer.
+ *
+ * @returns The handler, taking the query the schema describes.
+ */
+const cardHandler =
+  <TSchema extends z.ZodMiniType>(
+    schema: TSchema,
+    render: (params: z.output<TSchema>, colors: ColorParams, config: CardConfig) => Promise<string>,
+  ) =>
+  async (query: ApiQuery<TSchema>, config: CardConfig): Promise<ApiResult> => {
+    let colors: ColorParams;
+    try {
+      colors = parseColorParams(query);
+    } catch (error) {
+      return errorResult(error);
+    }
+
+    try {
+      return {
+        status: 'success',
+        content: await render(parseParams(schema, query), colors, config),
+      };
+    } catch (error) {
+      return errorResult(error, colors);
+    }
+  };
+
+export { cardHandler };

package/src/api/index.ts

@@ -1,16 +1,17 @@
-export { gist } from './gist.js';
-export { pin } from './pin.js';
-export { stats } from './stats.js';
-export { topLangs } from './top-langs.js';
-export { wakatime } from './wakatime.js';
+export { contributedTo } from './contributed-to.ts';
+export { gist } from './gist.ts';
+export { pin } from './pin.ts';
+export { stats } from './stats.ts';
+export { topLangs } from './top-langs.ts';
+export { wakatime } from './wakatime.ts';
 
-export type { ApiError, ApiResult } from './api-result.js';
+export type { ApiError, ApiResult } from './api-result.ts';
 
 // every handler but `wakatime` needs the PAT pool, and that one still needs the transport.
-export { CardConfig } from '../common/config.js';
-export type { CardConfigInit, PersonalAccessToken } from '../common/config.js';
-export type { FetchLike } from '../common/http.js';
-export type { ErrorCode } from '../common/error.js';
+export { CardConfig } from '../common/config.ts';
+export type { CardConfigInit, PersonalAccessToken } from '../common/config.ts';
+export type { FetchLike } from '../common/http.ts';
+export type { ErrorCode } from '../common/error.ts';
 
-export { themes } from '../themes/index.js';
-export type { ThemeName } from '../themes/index.js';
+export { themes } from '../themes/index.ts';
+export type { ThemeName } from '../themes/index.ts';

package/src/api/params.ts

@@ -1,10 +1,12 @@
 import * as z from 'zod/mini';
 
-import type { ColorParams } from '../common/color.js';
-import { COLOR_PARAM_KEYS, THEME_PARAM_KEYS, isValidColorInput } from '../common/color.js';
-import { CardError } from '../common/error.js';
-import { parseArray, parseBoolean } from '../common/ops.js';
-import { isLocaleAvailable } from '../translations.js';
+import type { ColorParams } from '../common/color.ts';
+import { COLOR_PARAM_KEYS, THEME_PARAM_KEYS, isValidColorInput } from '../common/color.ts';
+import { GITHUB_USERNAME_PATTERN } from '../common/constants.ts';
+import { getWidestRange, parseRangeDate } from '../common/date.ts';
+import { CardError } from '../common/error.ts';
+import { parseArray, parseBoolean } from '../common/ops.ts';
+import { isLocaleAvailable } from '../translations.ts';
 
 /**
  * @file The api layer is the trust boundary:
@@ -19,11 +21,20 @@ import { isLocaleAvailable } from '../translations.js';
 /** Every param arrives as a string, or not at all. */
 const rawParam = z.optional(z.string());
 
-/** Characters a username, repository, owner or gist id may contain. */
+/** Characters a repository, owner or gist id may contain. */
 const SAFE_PATTERN = /^[-\w/.,]+$/;
 
 /** What a check rejected a param for. */
-type Rejection = 'number' | 'year' | 'unsafe' | 'locale' | 'enum' | 'color';
+type Rejection =
+  | 'number'
+  | 'date'
+  | 'out_of_range'
+  | 'inverted_range'
+  | 'unsafe'
+  | 'username'
+  | 'locale'
+  | 'enum'
+  | 'color';
 
 /**
  * Every rejection the api can put on an error card, in one place.
@@ -31,8 +42,11 @@ type Rejection = 'number' | 'year' | 'unsafe' | 'locale' | 'enum' | 'color';
  */
 const REJECTION_MESSAGES: Record<Rejection, (param: string) => string> = {
   number: (param) => `Invalid number input for parameter "${param}"`,
-  year: (param) => `Invalid number input for parameter "${param}"`,
+  date: (param) => `Invalid date input for parameter "${param}"`,
+  out_of_range: (param) => `Out of range date for parameter "${param}"`,
+  inverted_range: () => 'Range "from" is after "to"',
   unsafe: (param) => `Parameter "${param}" contains unsafe characters`,
+  username: (param) => `Invalid username input for parameter "${param}"`,
   locale: () => 'Locale not found',
   enum: (param) => `Incorrect ${param} input`,
   color: (param) => `Invalid color input for parameter "${param}"`,
@@ -42,11 +56,9 @@ const REJECTION_MESSAGES: Record<Rejection, (param: string) => string> = {
  * A check that words its own rejection:
  * the message is built from the kind and the param's path rather than passed in.
  *
- * @param kind What the check rejects the param for.
- * @param passes Whether a value is acceptable.
  * @returns The check, ready for `.check()`.
  */
-const rejects = (kind: Rejection, passes: (value: string) => boolean) =>
+const rejects = (kind: Rejection, passes: (value: string) => boolean): z.core.$ZodCheck<unknown> =>
   z.refine((value: unknown) => typeof value !== 'string' || passes(value), {
     error: (issue) => REJECTION_MESSAGES[kind](String(issue.path?.[0] ?? '')),
   });
@@ -72,8 +84,8 @@ const listParam = z.pipe(rawParam, z.transform(parseArray));
  * Yields the parsed number, or `undefined` when the param is absent.
  */
 const numberParam: z.ZodMiniType<number | undefined, string | undefined> = z.pipe(
-  rawParam.check(rejects('number', (value) => Number.isFinite(parseFloat(value)))),
-  z.transform((value) => (value === undefined ? undefined : parseFloat(value))),
+  rawParam.check(rejects('number', (value) => Number.isFinite(Number.parseFloat(value)))),
+  z.transform((value) => (value === undefined ? undefined : Number.parseFloat(value))),
 );
 
 /**
@@ -82,17 +94,42 @@ const numberParam: z.ZodMiniType<number | undefined, string | undefined> = z.pip
  */
 const looseIntParam = z.pipe(
   rawParam,
-  z.transform((value) => (value === undefined ? undefined : parseInt(value, 10))),
+  z.transform((value) => (value === undefined ? undefined : Number.parseInt(value, 10))),
 );
 
 /**
- * A four-digit year.
- * Anything else builds a `DateTime` GitHub rejects, so it is a permanent error here rather than a failed request later.
- * Yields the year, or `undefined` when the param is absent.
+ * One end of the range a card counts within, written as `2024`, `2024-03` or `2024-03-15`.
+ *
+ * @returns Schema yielding the instant, or `undefined` when the param is absent.
  */
-const yearParam: z.ZodMiniType<number | undefined, string | undefined> = z.pipe(
-  rawParam.check(rejects('year', (value) => /^\d{4}$/.test(value))),
-  z.transform((value) => (value === undefined ? undefined : Number(value))),
+const rangeParam = (end: 'from' | 'to'): z.ZodMiniType<Date | undefined, string | undefined> => {
+  const parse = (value: string): Date | undefined => parseRangeDate(value, end);
+  return z.pipe(
+    rawParam.check(rejects('date', (value) => parse(value) !== undefined)).check(
+      rejects('out_of_range', (value) => {
+        const date = parse(value);
+        const widest = getWidestRange();
+        // a bad shape is already reported by the check above
+        return date === undefined || (date >= widest.from && date <= widest.to);
+      }),
+    ),
+    z.transform((value) => (value === undefined ? undefined : parse(value))),
+  );
+};
+
+/** The start of a card's range; see {@link rangeParam}. */
+const fromParam = rangeParam('from');
+
+/** The end of a card's range; see {@link rangeParam}. */
+const toParam = rangeParam('to');
+
+/**
+ * The pair-level rule the two ends cannot see on their own.
+ * Every endpoint taking a range applies it, so an order no card could draw is rejected once.
+ */
+const ORDERED_RANGE = z.refine<{ from?: Date | undefined; to?: Date | undefined }>(
+  ({ from, to }) => from === undefined || to === undefined || from <= to,
+  { error: REJECTION_MESSAGES.inverted_range('from'), path: ['from'] },
 );
 
 /**
@@ -103,6 +140,14 @@ const safeParam: z.ZodMiniType<string | undefined, string | undefined> = rawPara
   rejects('unsafe', (value) => !value || SAFE_PATTERN.test(value)),
 );
 
+/**
+ * A GitHub login, stricter than `safeParam`: no leading, trailing or doubled hyphen.
+ * Rejected here so a malformed one is a permanent error rather than the NOT_FOUND GitHub answers.
+ */
+const usernameParam: z.ZodMiniType<string | undefined, string | undefined> = rawParam.check(
+  rejects('username', (value) => !value || GITHUB_USERNAME_PATTERN.test(value)),
+);
+
 /**
  * A comma-separated list of ids, checked before it is split.
  * The safe pattern allows the commas, so one check covers the whole list.
@@ -126,7 +171,6 @@ const localeParam = z.pipe(
 /**
  * A param the card only renders as one of a fixed set of values.
  *
- * @param values The accepted values, as the card that renders them declares them.
  * @returns Schema yielding one of `values`, or `undefined` when absent.
  */
 const enumParam = <const T extends ReadonlyArray<string>>(
@@ -163,11 +207,10 @@ type ApiQuery<TSchema extends z.ZodMiniType> = Partial<z.input<TSchema>> & Color
  * Every rejection is the query's fault, so they share one code
  * and differ only in the message the check already worded.
  *
- * @param error What the schema rejected.
  * @returns The failure, ready to render.
  */
 const toCardError = (error: z.core.$ZodError): CardError => {
-  const issue = error.issues[0];
+  const [issue] = error.issues;
   return CardError.invalidParam(String(issue?.path[0] ?? ''), issue?.message ?? 'Invalid input');
 };
 
@@ -177,10 +220,9 @@ const toCardError = (error: z.core.$ZodError): CardError => {
  * Only the first rejection is reported:
  * the error card has room for one line.
  *
- * @param schema The endpoint's schema.
- * @param query Raw query params.
- * @returns The parsed params.
  * @throws {CardError} When the schema rejects a param.
+ *
+ * @returns The parsed params.
  */
 const parseParams = <TSchema extends z.ZodMiniType>(
   schema: TSchema,
@@ -197,9 +239,9 @@ const parseParams = <TSchema extends z.ZodMiniType>(
  * The color params, validated.
  * Split from the endpoint's own schema because a rejected color cannot then be used to render its own error card.
  *
- * @param query Raw query params.
- * @returns The color params.
  * @throws {CardError} When a param does not hold a color or a gradient.
+ *
+ * @returns The color params.
  */
 const parseColorParams = (query: unknown): ColorParams => parseParams(colorParamsSchema, query);
 
@@ -208,7 +250,9 @@ export type { ApiQuery };
 export {
   booleanParam,
   enumParam,
+  fromParam,
   listParam,
+  ORDERED_RANGE,
   localeParam,
   looseIntParam,
   numberParam,
@@ -217,5 +261,6 @@ export {
   rawParam,
   safeListParam,
   safeParam,
-  yearParam,
+  toParam,
+  usernameParam,
 };