Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

10.1 KB
Raw Blame
#!/usr/bin/env node
// Builds a README contributors wall from the GitHub contributors API.
// Avatar bytes are inlined as base64 so GitHub's image proxy does not have to
// fetch nested images. The scheduled workflow publishes the file on a data
// branch; this script does not commit.

import fs from 'node:fs';
import { pathToFileURL } from 'node:url';

const WALL_WIDTH = 1000;
const COLUMNS = 8;
const AVATAR = 72;
const CELL_WIDTH = WALL_WIDTH / COLUMNS;
const AVATAR_X = (CELL_WIDTH - AVATAR) / 2;
const AVATAR_Y = 8;
const NAME_LIMIT = 18;
const ROW_HEIGHT = AVATAR_Y + AVATAR + 36;
const MAX_AVATAR_BYTES = 1_500_000;

// Exact logins, plus any account GitHub marks as a Bot or names with [bot].
// "claude" is the unscoped Claude app login, not a substring of human names.
const BOT_LOGINS = new Set([
  'allcontributors',
  'claude',
  'codecov',
  'copilot',
  'dependabot',
  'dependabot-preview',
  'github-actions',
  'imgbot',
  'pre-commit-ci',
  'renovate',
  'snyk-bot',
  'web-flow',
]);

const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;

export function isBotContributor(user) {
  if (!user || typeof user.login !== 'string') return true;
  if (user.type === 'Bot') return true;
  const login = user.login.trim();
  if (/\[bot\]$/i.test(login)) return true;
  return BOT_LOGINS.has(login.toLowerCase());
}

export function displayLogin(login) {
  if (login.length <= NAME_LIMIT) return login;
  return `${login.slice(0, NAME_LIMIT - 1)}…`;
}

export function avatarMediaType(bytes, headerType = '') {
  if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return 'image/png';
  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg';
  const gif = bytes.length >= 6 ? bytes.subarray(0, 6).toString('ascii') : '';
  if (gif === 'GIF87a' || gif === 'GIF89a') return 'image/gif';
  if (bytes.length >= 12 && bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP') return 'image/webp';
  const normalized = String(headerType).split(';')[0].trim().toLowerCase();
  if (['image/png', 'image/jpeg', 'image/gif', 'image/webp'].includes(normalized)) return normalized;
  throw new Error('Avatar is not a PNG, JPEG, GIF, or WebP image');
}

function xmlEscape(value) {
  return value.replace(/[&<>"']/g, (char) => ({
    '&': '&amp;',
    '<': '&lt;',
    '>': '&gt;',
    '"': '&quot;',
    "'": '&apos;',
  }[char]));
}

function repoParts(repo) {
  const match = /^([^/\s]+)\/([^/\s]+)$/.exec(repo || '');
  if (!match) throw new Error('Repository must look like owner/name');
  return { owner: match[1], name: match[2] };
}

function githubHeaders(token, accept = 'application/vnd.github+json') {
  const headers = {
    Accept: accept,
    'User-Agent': 'archify-contributors-svg',
    'X-GitHub-Api-Version': '2022-11-28',
  };
  if (token) headers.Authorization = `Bearer ${token}`;
  return headers;
}

function nextPage(linkHeader) {
  if (!linkHeader) return '';
  for (const part of linkHeader.split(',')) {
    const match = /<([^>]+)>;\s*rel="next"/.exec(part);
    if (!match) continue;
    const url = new URL(match[1]);
    if (url.protocol !== 'https:' || url.hostname !== 'api.github.com') {
      throw new Error('Refusing contributors pagination outside api.github.com');
    }
    return url.href;
  }
  return '';
}

export async function fetchContributors({ repo = 'tt-a1i/archify', token = '', fetchImpl = fetch } = {}) {
  const { owner, name } = repoParts(repo);
  let url = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contributors?per_page=100`;
  const people = [];
  const seen = new Set();
  while (url) {
    const response = await fetchImpl(url, {
      headers: githubHeaders(token),
      signal: AbortSignal.timeout(20_000),
    });
    if (!response.ok) throw new Error(`GitHub contributors request failed (${response.status})`);
    const page = await response.json();
    if (!Array.isArray(page)) throw new Error('GitHub contributors response was not a list');
    for (const user of page) {
      if (isBotContributor(user) || seen.has(user.login)) continue;
      if (!LOGIN.test(user.login)) continue;
      seen.add(user.login);
      people.push({
        login: user.login,
        contributions: Number(user.contributions) || 0,
        avatarUrl: user.avatar_url,
      });
    }
    url = nextPage(response.headers.get('link'));
  }
  people.sort((a, b) => b.contributions - a.contributions || a.login.localeCompare(b.login));
  if (!people.length) throw new Error('No human contributors to render');
  return people;
}

function avatarRequestUrl(avatarUrl, login) {
  let url;
  try {
    url = new URL(avatarUrl);
  } catch {
    throw new Error(`Contributor ${login} has no avatar URL`);
  }
  if (url.protocol !== 'https:' || !['avatars.githubusercontent.com', 'github.com'].includes(url.hostname)) {
    throw new Error(`Refusing avatar host for ${login}`);
  }
  url.searchParams.set('s', '144');
  return url;
}

export async function fetchAvatarDataUri(person, { fetchImpl = fetch } = {}) {
  let requested = avatarRequestUrl(person.avatarUrl, person.login);
  let response;
  for (let redirects = 0; ; redirects += 1) {
    // Avatars are public. Keep the API token on the API request path only.
    response = await fetchImpl(requested, {
      headers: githubHeaders('', 'application/octet-stream'),
      redirect: 'manual',
      signal: AbortSignal.timeout(20_000),
    });
    if (![301, 302, 303, 307, 308].includes(response.status)) break;
    await response.body?.cancel();
    const location = response.headers.get('location');
    if (!location) throw new Error(`Avatar redirect has no location for ${person.login}`);
    if (redirects >= 5) throw new Error(`Too many avatar redirects for ${person.login}`);
    // Validate each hop before fetching it, including HTTPS and allowed hosts.
    requested = avatarRequestUrl(new URL(location, requested).href, person.login);
  }
  if (!response.ok) throw new Error(`Avatar download failed for ${person.login} (${response.status})`);
  avatarRequestUrl(response.url || requested, person.login);
  const bytes = Buffer.from(await response.arrayBuffer());
  if (bytes.length === 0 || bytes.length > MAX_AVATAR_BYTES) {
    throw new Error(`Avatar for ${person.login} is empty or larger than ${MAX_AVATAR_BYTES} bytes`);
  }
  const mediaType = avatarMediaType(bytes, response.headers.get('content-type') || '');
  return `data:${mediaType};base64,${bytes.toString('base64')}`;
}

export function renderContributorsSvg(contributors) {
  if (!Array.isArray(contributors) || contributors.length === 0) {
    throw new Error('No human contributors to render');
  }
  const rows = Math.ceil(contributors.length / COLUMNS);
  const cells = contributors.map((person, index) => {
    if (!person || !LOGIN.test(person.login || '')) throw new Error('Contributor login is not a GitHub login');
    if (!/^data:image\/(?:png|jpeg|gif|webp);base64,[A-Za-z0-9+/=]+$/.test(person.dataUri || '')) {
      throw new Error(`Contributor ${person.login} is missing an inline avatar`);
    }
    const column = index % COLUMNS;
    const row = Math.floor(index / COLUMNS);
    const label = displayLogin(person.login);
    const centerX = AVATAR_X + AVATAR / 2;
    const centerY = AVATAR_Y + AVATAR / 2;
    return `  <g transform="translate(${column * CELL_WIDTH} ${row * ROW_HEIGHT})">
    <title>${xmlEscape(person.login)}</title>
    <defs><clipPath id="archify-contributor-${index}"><circle cx="${centerX}" cy="${centerY}" r="${AVATAR / 2}"/></clipPath></defs>
    <image href="${person.dataUri}" x="${AVATAR_X}" y="${AVATAR_Y}" width="${AVATAR}" height="${AVATAR}" clip-path="url(#archify-contributor-${index})" preserveAspectRatio="xMidYMid slice"/>
    <circle class="ring" cx="${centerX}" cy="${centerY}" r="${AVATAR / 2}" fill="none" stroke-width="1"/>
    <text class="name" x="${centerX}" y="${AVATAR_Y + AVATAR + 22}" text-anchor="middle">${xmlEscape(label)}</text>
  </g>`;
  });
  return `<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="${WALL_WIDTH}" height="${rows * ROW_HEIGHT}" viewBox="0 0 ${WALL_WIDTH} ${rows * ROW_HEIGHT}" role="img">
  <title>Archify contributors</title>
  <style><![CDATA[
    .name { fill: #24292f; stroke: #ffffff; stroke-width: 3px; paint-order: stroke fill; font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; font-size: 12px; }
    .ring { stroke: #d0d7de; }
    @media (prefers-color-scheme: dark) {
      .name { fill: #f0f6fc; stroke: #010409; }
      .ring { stroke: #30363d; }
    }
  ]]></style>
${cells.join('\n')}
</svg>
`;
}

export async function buildContributorsSvg(options = {}) {
  const people = await fetchContributors(options);
  const rendered = [];
  for (const person of people) {
    rendered.push({
      login: person.login,
      dataUri: await fetchAvatarDataUri(person, options),
    });
  }
  return renderContributorsSvg(rendered);
}

function parseArgs(argv) {
  const options = { repo: 'tt-a1i/archify', out: '' };
  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === '--repo') options.repo = argv[++index];
    else if (arg === '--out') options.out = argv[++index];
    else if (arg === '--help' || arg === '-h') options.help = true;
    else throw new Error(`Unknown argument: ${arg}`);
    if (options.repo === undefined || options.out === undefined) throw new Error(`Missing value for ${arg}`);
  }
  return options;
}

async function main(argv, env = process.env) {
  const options = parseArgs(argv);
  if (options.help) {
    console.log('Usage: node scripts/generate-contributors-svg.mjs [--repo owner/name] [--out file]');
    return;
  }
  const svg = await buildContributorsSvg({
    repo: options.repo,
    token: env.GH_TOKEN || env.GITHUB_TOKEN || '',
  });
  if (options.out) fs.writeFileSync(options.out, svg);
  else process.stdout.write(svg);
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main(process.argv.slice(2)).catch((error) => {
    console.error(error.message);
    process.exit(1);
  });
}