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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stats-forge/github-stats-forge-core",
-  "version": "0.0.2",
+  "version": "0.1.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/gist.ts

@@ -1,13 +1,13 @@
 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 type { CardConfig } from '../common/config.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 type { ApiResult } from './api-result.ts';
+import { errorResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
+import { booleanParam, numberParam, parseColorParams, parseParams, safeParam } from './params.ts';
 
 /** What the gist endpoint accepts, on top of the shared color params. */
 const gistQuery = z.object({
@@ -24,22 +24,15 @@ 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) {
+  } catch (error) {
     // A rejected color cannot be used to draw its own error card.
-    return errorResult(err);
+    return errorResult(error);
   }
 
   try {
@@ -60,7 +53,7 @@ export const gist = async (query: GistApiQuery, config: CardConfig): Promise<Api
         hide_border,
       }),
     };
-  } catch (err) {
-    return errorResult(err, colors);
+  } catch (error) {
+    return errorResult(error, colors);
   }
 };

package/src/api/index.ts

@@ -1,16 +1,16 @@
-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 { 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,11 @@
 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 { 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 +20,11 @@ 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' | 'year' | 'unsafe' | 'username' | 'locale' | 'enum' | 'color';
 
 /**
  * Every rejection the api can put on an error card, in one place.
@@ -33,6 +34,7 @@ const REJECTION_MESSAGES: Record<Rejection, (param: string) => string> = {
   number: (param) => `Invalid number input for parameter "${param}"`,
   year: (param) => `Invalid number input for parameter "${param}"`,
   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 +44,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 +72,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,7 +82,7 @@ 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))),
 );
 
 /**
@@ -103,6 +103,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 +134,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 +170,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 +183,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 +202,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);
 
@@ -217,5 +222,6 @@ export {
   rawParam,
   safeListParam,
   safeParam,
+  usernameParam,
   yearParam,
 };

package/src/api/pin.ts

@@ -1,12 +1,12 @@
 import * as z from 'zod/mini';
 
-import { renderRepoCard } from '../cards/repo.js';
-import type { CardConfig } from '../common/config.js';
-import { fetchRepo } from '../fetchers/repo.js';
+import { renderRepoCard } from '../cards/repo.ts';
+import type { CardConfig } from '../common/config.ts';
+import { fetchRepo } from '../fetchers/repo.ts';
 
-import type { ApiResult } from './api-result.js';
-import { errorResult } from './api-result.js';
-import type { ApiQuery } from './params.js';
+import type { ApiResult } from './api-result.ts';
+import { errorResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
 import {
   booleanParam,
   listParam,
@@ -17,11 +17,12 @@ import {
   parseParams,
   rawParam,
   safeParam,
-} from './params.js';
+  usernameParam,
+} from './params.ts';
 
 /** What the pin endpoint accepts, on top of the shared color params. */
 const pinQuery = z.object({
-  username: safeParam,
+  username: usernameParam,
   repo: safeParam,
   hide_border: booleanParam,
   card_width: looseIntParam,
@@ -43,31 +44,15 @@ type PinApiQuery = ApiQuery<typeof pinQuery>;
 /**
  * Render the repository card for a set of query params.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.username GitHub username the repository belongs to.
- * @param query.repo Repository name.
- * @param query.hide_border Whether to hide the card border.
- * @param query.card_width Card width.
- * @param query.show_owner Whether to show the repository owner.
- * @param query.browser_rendering Whether the browser wraps the description text.
- * @param query.show Comma-separated extra stats to show.
- * @param query.show_icons Whether to show the stat icons.
- * @param query.number_format How numbers are abbreviated.
- * @param query.text_bold Whether the stat values are bold.
- * @param query.line_height Line height between the stats.
- * @param query.locale Language the card is rendered in.
- * @param query.border_radius Card border radius.
- * @param query.description_lines_count Lines the description is wrapped to.
- * @param config Deployment config supplying the PAT pool.
  * @returns The rendered card, or a rendered error.
  */
 export const pin = async (query: PinApiQuery, config: CardConfig): Promise<ApiResult> => {
   let colors;
   try {
     colors = parseColorParams(query);
-  } catch (err) {
+  } catch (error) {
     // A rejected color cannot be used to draw its own error card.
-    return errorResult(err);
+    return errorResult(error);
   }
 
   try {
@@ -120,7 +105,7 @@ export const pin = async (query: PinApiQuery, config: CardConfig): Promise<ApiRe
         description_lines_count,
       }),
     };
-  } catch (err) {
-    return errorResult(err, colors);
+  } catch (error) {
+    return errorResult(error, colors);
   }
 };

package/src/api/stats.ts

@@ -1,12 +1,12 @@
 import * as z from 'zod/mini';
 
-import { RANK_ICONS, renderStatsCard } from '../cards/stats.js';
-import type { CardConfig } from '../common/config.js';
-import { fetchStats } from '../fetchers/stats.js';
+import { RANK_ICONS, renderStatsCard } from '../cards/stats.ts';
+import type { CardConfig } from '../common/config.ts';
+import { fetchStats } from '../fetchers/stats.ts';
 
-import type { ApiResult } from './api-result.js';
-import { errorResult } from './api-result.js';
-import type { ApiQuery } from './params.js';
+import type { ApiResult } from './api-result.ts';
+import { errorResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
 import {
   booleanParam,
   enumParam,
@@ -18,13 +18,13 @@ import {
   parseParams,
   rawParam,
   safeListParam,
-  safeParam,
+  usernameParam,
   yearParam,
-} from './params.js';
+} from './params.ts';
 
 /** What the stats endpoint accepts, on top of the shared color params. */
 const statsQuery = z.object({
-  username: safeParam,
+  username: usernameParam,
   repo: safeListParam,
   owner: safeListParam,
   hide: listParam,
@@ -56,41 +56,15 @@ type StatsApiQuery = ApiQuery<typeof statsQuery>;
 /**
  * Render the stats card for a set of query params.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.username GitHub username.
- * @param query.repo Comma-separated repositories the search-based stats are scoped to.
- * @param query.owner Comma-separated owners the search-based stats are scoped to.
- * @param query.hide Comma-separated stats to hide.
- * @param query.hide_title Whether to hide the card title.
- * @param query.hide_border Whether to hide the card border.
- * @param query.card_width Card width.
- * @param query.hide_rank Whether to hide the rank circle.
- * @param query.show_icons Whether to show the stat icons.
- * @param query.include_all_commits Whether to count commits of all time.
- * @param query.commits_year Year the commits are counted for.
- * @param query.line_height Line height between the stats.
- * @param query.text_bold Whether the stat values are bold.
- * @param query.exclude_repo Comma-separated repositories to exclude.
- * @param query.custom_title Card title.
- * @param query.locale Language the card is rendered in.
- * @param query.disable_animations Whether to disable the card animations.
- * @param query.border_radius Card border radius.
- * @param query.number_format How numbers are abbreviated.
- * @param query.role Comma-separated owner affiliations to include.
- * @param query.number_precision Decimals kept when a number is abbreviated.
- * @param query.rank_icon Which rank indicator to draw.
- * @param query.show Comma-separated extra stats to show.
- * @param query.contribs_include_own_repos Whether the contributed-to counts include the user's own repositories.
- * @param config Deployment config supplying the PAT pool.
  * @returns The rendered card, or a rendered error.
  */
 const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<ApiResult> => {
   let colors;
   try {
     colors = parseColorParams(query);
-  } catch (err) {
+  } catch (error) {
     // A rejected color cannot be used to draw its own error card.
-    return errorResult(err);
+    return errorResult(error);
   }
 
   try {
@@ -181,8 +155,8 @@ const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<Ap
         owner,
       ),
     };
-  } catch (err) {
-    return errorResult(err, colors);
+  } catch (error) {
+    return errorResult(error, colors);
   }
 };
 

package/src/api/top-langs.ts

@@ -4,13 +4,13 @@ import {
   TOP_LANG_LAYOUTS,
   TOP_LANG_STATS_FORMATS,
   renderTopLanguages,
-} from '../cards/top-languages.js';
-import type { CardConfig } from '../common/config.js';
-import { fetchTopLanguages } from '../fetchers/top-languages.js';
+} from '../cards/top-languages.ts';
+import type { CardConfig } from '../common/config.ts';
+import { fetchTopLanguages } from '../fetchers/top-languages.ts';
 
-import type { ApiResult } from './api-result.js';
-import { errorResult } from './api-result.js';
-import type { ApiQuery } from './params.js';
+import type { ApiResult } from './api-result.ts';
+import { errorResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
 import {
   booleanParam,
   enumParam,
@@ -21,12 +21,12 @@ import {
   parseColorParams,
   parseParams,
   rawParam,
-  safeParam,
-} from './params.js';
+  usernameParam,
+} from './params.ts';
 
 /** What the top-languages endpoint accepts, on top of the shared color params. */
 const topLangsQuery = z.object({
-  username: safeParam,
+  username: usernameParam,
   hide: listParam,
   hide_title: booleanParam,
   hide_border: booleanParam,
@@ -52,35 +52,15 @@ type TopLangsApiQuery = ApiQuery<typeof topLangsQuery>;
 /**
  * Render the top languages card for a set of query params.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.username GitHub username.
- * @param query.hide Comma-separated languages to hide.
- * @param query.hide_title Whether to hide the card title.
- * @param query.hide_border Whether to hide the card border.
- * @param query.card_width Card width.
- * @param query.layout How the languages are laid out.
- * @param query.langs_count Number of languages to show.
- * @param query.exclude_repo Comma-separated repositories to exclude.
- * @param query.size_weight Weight given to a language's size.
- * @param query.count_weight Weight given to a language's repository count.
- * @param query.custom_title Card title.
- * @param query.locale Language the card is rendered in.
- * @param query.border_radius Card border radius.
- * @param query.role Comma-separated owner affiliations to include.
- * @param query.disable_animations Whether to disable the card animations.
- * @param query.hide_progress Whether to hide the progress bars.
- * @param query.hide_values Whether to hide the language values.
- * @param query.stats_format Whether values are shown as bytes or percentages.
- * @param config Deployment config supplying the PAT pool.
  * @returns The rendered card, or a rendered error.
  */
 const renderTopLangs = async (query: TopLangsApiQuery, config: CardConfig): Promise<ApiResult> => {
   let colors;
   try {
     colors = parseColorParams(query);
-  } catch (err) {
+  } catch (error) {
     // A rejected color cannot be used to draw its own error card.
-    return errorResult(err);
+    return errorResult(error);
   }
 
   try {
@@ -135,8 +115,8 @@ const renderTopLangs = async (query: TopLangsApiQuery, config: CardConfig): Prom
         stats_format,
       }),
     };
-  } catch (err) {
-    return errorResult(err, colors);
+  } catch (error) {
+    return errorResult(error, colors);
   }
 };