Gitface

Transparent featured-face picker: gitrank Card[] → who to feature for a country or any cohort.

Gitface is a pure TypeScript library. It does not call GitHub, touch Redis, render OG images, or apply editorial overrides. You supply scored cards (from gitrank); it returns a deterministic pick you can audit, fork, and tune.

Part of gitwork-oss.

Why it exists

Hosts often need a single “face” for a country page, Open Graph preview, or national squad. Hard-coding that map inside a ranking library hides curation as science. Gitface keeps selection policy-named and open; product overrides stay in the host.

Story: gitrank scores one profile; gitface chooses the face of a cohort.

Install

git clone https://github.com/gitwork-oss/gitface.git
cd gitface
npm install

Peer dependency: gitrank (types + Card shape). Dev installs resolve it from github:gitwork-oss/gitrank so clone + npm test works without a sibling checkout.

Import from source (TypeScript / ESM):

import { pickFeatured } from "gitface";
// or relative: import { pickFeatured } from "./src/index.ts";

There is no published npm build step yet — consume the TypeScript entry at src/index.ts.

Quick start

import { pickFeatured, type Card } from "gitface";

const cards: Card[] = /* from gitrank buildCard / your cache */;

const result = pickFeatured(cards, {
  policy: "ovr", // default
  country: "bw", // optional ISO filter on card.country
});

if (result) {
  console.log(result.login, result.reason, result.policy);
}

Policies

Policy	Behavior
ovr (default)	Highest card.overall; tiebreak login ascending
active-ovr	Same as ovr, but only among cards at/above minRecentContributions (default 50). Pass activity via recentContributionsByLogin. If nobody clears the floor, falls back to the full pool
showcase	Prefer family === "Forward" when within showcaseMargin OVR of the leader (default 3); else highest OVR

pickFeatured(cards, {
  policy: "active-ovr",
  minRecentContributions: 50,
  recentContributionsByLogin: { alice: 200, bob: 10 },
});

pickFeatured(cards, {
  policy: "showcase",
  showcaseMargin: 3,
});

rankFeatured returns the full ordered list (best first) under the same options.

Host overrides (not in this package)

Editorial picks (marketing, launch countries) belong in the host, not in gitface:

const OVERRIDES: Record<string, string> = { /* country → login */ };

function featuredLogin(country: string, pool: Card[], fallback: string): string {
  if (OVERRIDES[country]) return OVERRIDES[country];
  return pickFeatured(pool, { policy: "ovr", country })?.login ?? fallback;
}

Non-goals

• No override / allowlist maps
• No Open Graph / Satori / image rendering
• No GitHub discovery or scouting
• No geo-IP
• No multi-signal “influence” score fighting gitrank OVR (add a named policy later if needed)

API

Export	Role
pickFeatured(cards, options?)	Best face, or null if pool empty
rankFeatured(cards, options?)	Full ranking under the policy
compareByOvr	Shared OVR + login comparator
DEFAULT_MIN_RECENT_CONTRIBUTIONS	50
DEFAULT_SHOWCASE_MARGIN	3

PickFeaturedOptions

Field	Meaning
policy	ovr | active-ovr | showcase
country	Optional ISO filter on card.country
minRecentContributions	Floor for active-ovr
recentContributionsByLogin	Side-channel: lowercase login → recent contributions
showcaseMargin	OVR band for Forward preference

Layout

src/
  index.ts           public exports
  pickFeatured.ts    rank + pick
  config.ts          default knobs
  types.ts           options / result types
  testing/           fixtures (not shipped as API)
  **/__tests__/      Vitest

License

MIT — see LICENSE.