@cratis/cast 0.0.0-stage → 0.1.0

package/github/fetchGitHub.ts

@@ -0,0 +1,235 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { cratisOrganization } from '../badges/constants';
+import type { GitHubSnapshot, Release } from './GitHubSnapshot';
+import { mergedPullRequestQuery, parseCalendar, parseMergedPullRequests, standingAmongHumans, type CalendarWeekNode, type ContributorEntry, type PullRequestNode } from './parse';
+
+/** What to capture. */
+export type GitHubRequest = {
+    login: string;
+    orgs: string[];
+    /** owner/name repositories to compute commit rank and merged pull requests for. */
+    repositories: string[];
+    releases: string[];
+    stars: string[];
+    feedLimit?: number;
+    /** Spacing between search requests (search has its own 30-per-minute limit). Default 2100 ms. */
+    searchDelayMilliseconds?: number;
+};
+
+/**
+ * Evidence fetched in this call only, for granting tiers. Never persisted: a snapshot is owner-editable, so
+ * nothing read from one may grant a tier.
+ */
+export type FreshEvidence = {
+    /** Merged public pull requests in the Cratis organization, when the search succeeded in this call. */
+    cratisMergedPullRequests?: number;
+};
+
+/** A fetch result: the snapshot to render and persist, and the evidence that is used for tiers and then dropped. */
+export type GitHubFetchResult = { snapshot: GitHubSnapshot; fresh: FreshEvidence };
+
+/** Receives warnings; the fetch itself never throws. */
+export type Warn = (message: string) => void;
+
+const userAgent = 'cratis-cast-build';
+const sleep = (milliseconds: number) => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+/** Reads the token the build should use, if any. */
+export const gitHubToken = (): string | undefined => process.env.GITHUB_TOKEN || process.env.GH_TOKEN || undefined;
+
+async function rest(path: string, token: string): Promise<Response> {
+    const response = await fetch(`https://api.github.com${path}`, {
+        headers: { authorization: `bearer ${token}`, accept: 'application/vnd.github+json', 'user-agent': userAgent },
+        signal: AbortSignal.timeout(20_000),
+    });
+    if (response.status !== 200) throw new Error(`${path}: GitHub answered ${response.status}`);
+    return response;
+}
+
+/**
+ * Runs a GraphQL query; throws on transport errors and on GraphQL errors. With `allowPartial`, GraphQL errors
+ * (such as one unknown login in a batch) are reported through `onErrors` and whatever data came back is returned.
+ */
+export async function graphql<T>(query: string, variables: Record<string, unknown>, token: string, partial?: { allowPartial: true; onErrors: (messages: string[]) => void }): Promise<T> {
+    const response = await fetch('https://api.github.com/graphql', {
+        method: 'POST',
+        headers: { authorization: `bearer ${token}`, 'content-type': 'application/json', 'user-agent': userAgent },
+        body: JSON.stringify({ query, variables }),
+        signal: AbortSignal.timeout(25_000),
+    });
+    if (!response.ok) throw new Error(`GitHub GraphQL answered ${response.status} ${response.statusText}`);
+    const body = await response.json() as { data?: T; errors?: { message: string }[] };
+    if (body.errors?.length) {
+        const messages = body.errors.map(error => error.message);
+        if (!partial || !body.data) throw new Error(`GraphQL errors: ${messages.join('; ')}`);
+        partial.onErrors(messages);
+    }
+    if (!body.data) throw new Error('GraphQL returned no data');
+    return body.data;
+}
+
+/** Counts search results. Search has its own 30-per-minute limit, so calls are spaced out. */
+export async function searchCount(query: string, token: string, delayMilliseconds = 2100): Promise<number> {
+    await sleep(delayMilliseconds);
+    const body = await (await rest(`/search/issues?q=${encodeURIComponent(query)}&per_page=1`, token)).json() as { total_count?: number; incomplete_results?: boolean };
+    if (!Number.isInteger(body.total_count) || body.incomplete_results) throw new Error('incomplete search response');
+    return body.total_count!;
+}
+
+async function contributors(repository: string, token: string): Promise<ContributorEntry[]> {
+    const all: ContributorEntry[] = [];
+    for (let page = 1; page <= 10; page++) {
+        const path = `/repos/${repository}/contributors?per_page=100&page=${page}`;
+        let response: Response;
+        try {
+            response = await rest(path, token);
+        } catch (error) {
+            // 202 means GitHub is still computing the statistics; one retry is enough for a build.
+            if (!String(error).includes('answered 202')) throw error;
+            await sleep(1000);
+            response = await rest(path, token);
+        }
+        const items = await response.json() as ContributorEntry[];
+        all.push(...items);
+        if (!response.headers.get('link')?.includes('rel="next"')) break;
+    }
+    if (all.length === 0) throw new Error(`${repository}: no contributors returned`);
+    return all;
+}
+
+const alias = (index: number) => `r${index}`;
+const split = (repository: string): [string, string] => {
+    const [owner, name] = repository.split('/');
+    return [owner ?? '', name ?? ''];
+};
+
+/**
+ * Captures public GitHub data. Returns undefined when nothing could be captured; per-repository failures keep
+ * that repository's previous values. Never throws.
+ */
+export async function fetchGitHub(request: GitHubRequest, token: string, previous: GitHubSnapshot | undefined, warn: Warn): Promise<GitHubFetchResult | undefined> {
+    const delay = request.searchDelayMilliseconds ?? 2100;
+    const tracked = [...new Set([...request.releases, ...request.stars, ...request.repositories])];
+    const repositoryFields = tracked.map((repository, index) => {
+        const [owner, name] = split(repository);
+        return `${alias(index)}: repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { nameWithOwner isPrivate stargazerCount latestRelease { tagName publishedAt url } }`;
+    }).join('\n  ');
+
+    const query = `query($login: String!, $prs: String!) {
+  user(login: $login) {
+    login name bio location websiteUrl avatarUrl
+    followers { totalCount }
+    repositories(privacy: PUBLIC) { totalCount }
+    contributionsCollection {
+      totalCommitContributions
+      contributionCalendar { totalContributions weeks { contributionDays { date contributionCount } } }
+    }
+  }
+  ${repositoryFields}
+  merged: search(query: $prs, type: ISSUE, first: 60) {
+    issueCount
+    nodes { ... on PullRequest { title number url mergedAt repository { nameWithOwner isPrivate } } }
+  }
+}`;
+
+    type RepositoryNode = { nameWithOwner: string; isPrivate: boolean; stargazerCount: number; latestRelease: { tagName: string; publishedAt: string; url: string } | null } | null;
+    type Data = {
+        user: {
+            login: string; name: string | null; bio: string | null; location: string | null; websiteUrl: string | null; avatarUrl: string | null;
+            followers: { totalCount: number }; repositories: { totalCount: number };
+            contributionsCollection: { totalCommitContributions: number; contributionCalendar: { totalContributions: number; weeks: CalendarWeekNode[] } };
+        } | null;
+        merged: { issueCount: number; nodes: PullRequestNode[] };
+    } & Record<string, RepositoryNode>;
+
+    let data: Data;
+    try {
+        data = await graphql<Data>(query, { login: request.login, prs: `${mergedPullRequestQuery(request.login, request.orgs)} sort:updated-desc` }, token);
+    } catch (error) {
+        warn(error instanceof Error ? error.message : String(error));
+        return undefined;
+    }
+    if (!data.user) {
+        warn(`GitHub has no user '${request.login}'`);
+        return undefined;
+    }
+
+    const publicRepository = (repository: string): RepositoryNode | undefined => {
+        const node = data[alias(tracked.indexOf(repository))];
+        return node && node.isPrivate === false ? node : undefined;
+    };
+
+    const releases: Record<string, Release> = {};
+    for (const repository of request.releases) {
+        const release = publicRepository(repository)?.latestRelease;
+        if (release) releases[repository] = { tag: release.tagName, publishedAt: release.publishedAt, url: release.url };
+    }
+    const stars: Record<string, number> = {};
+    for (const repository of request.stars) {
+        const node = publicRepository(repository);
+        if (node) stars[repository] = node.stargazerCount;
+    }
+
+    const repositories: GitHubSnapshot['repositories'] = {};
+    for (const repository of request.repositories) {
+        // Never keep even an older snapshot for a repository that is not public now.
+        if (!publicRepository(repository)) continue;
+        const kept = previous?.repositories[repository];
+        if (kept) repositories[repository] = kept;
+        try {
+            const standing = standingAmongHumans(await contributors(repository, token), request.login);
+            const prs = await searchCount(`author:${request.login} repo:${repository} is:public is:pr is:merged`, token, delay);
+            repositories[repository] = { ...standing, prs };
+        } catch (error) {
+            warn(`${repository}: ${error instanceof Error ? error.message : String(error)} (keeping previous values)`);
+        }
+    }
+
+    const byOrg: Record<string, number> = {};
+    const fresh: FreshEvidence = {};
+    for (const org of new Set([...request.orgs, cratisOrganization])) {
+        try {
+            byOrg[org] = await searchCount(mergedPullRequestQuery(request.login, [org]), token, delay);
+            if (org === cratisOrganization && data.user.login.toLowerCase() === request.login.toLowerCase()) fresh.cratisMergedPullRequests = byOrg[org];
+        } catch (error) {
+            // The previous count is kept for display only; it never becomes evidence.
+            const kept = previous?.mergedPullRequests.byOrg[org];
+            if (kept !== undefined) byOrg[org] = kept;
+            warn(`${org} merged pull requests: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    const user = data.user;
+    const calendar = user.contributionsCollection.contributionCalendar;
+    const snapshot: GitHubSnapshot = {
+        fetchedAt: new Date().toISOString(),
+        login: user.login,
+        orgs: request.orgs,
+        profile: {
+            login: user.login,
+            name: user.name ?? undefined,
+            bio: user.bio ?? undefined,
+            location: user.location ?? undefined,
+            blog: user.websiteUrl ?? undefined,
+            avatarUrl: user.avatarUrl ?? undefined,
+            followers: user.followers.totalCount,
+            publicRepositories: user.repositories.totalCount,
+        },
+        contributions: {
+            total: calendar.totalContributions,
+            commits: user.contributionsCollection.totalCommitContributions,
+            weeks: parseCalendar(calendar.weeks),
+        },
+        mergedPullRequests: {
+            total: data.merged.issueCount,
+            byOrg,
+            latest: parseMergedPullRequests(data.merged.nodes, request.feedLimit ?? 12),
+        },
+        repositories,
+        releases,
+        stars,
+    };
+    return { snapshot, fresh };
+}

package/github/parse.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ContributionWeek, PullRequest } from './GitHubSnapshot';
+
+/** A contributor as the REST contributors endpoint returns it. */
+export type ContributorEntry = { login: string; type?: string; contributions: number };
+
+/** A pull request node as the GraphQL search returns it. */
+export type PullRequestNode = {
+    title?: string;
+    number?: number;
+    url?: string;
+    mergedAt?: string | null;
+    repository?: { nameWithOwner?: string; name?: string; owner?: { login?: string }; isPrivate?: boolean };
+} | null;
+
+const botLogins = new Set(['cratis-bot', 'dependabot', 'github-actions', 'renovate', 'copilot', 'copilot-swe-agent']);
+
+/** True for bots: GitHub's Bot type, `[bot]` and `-bot` logins, and well-known automation accounts. */
+export function isBot(entry: { login: string; type?: string }): boolean {
+    const login = entry.login.toLowerCase();
+    return entry.type === 'Bot' || login.endsWith('[bot]') || login.endsWith('-bot') || botLogins.has(login);
+}
+
+/** Commits and 1-based rank of `login` among human contributors; rank 0 when absent. */
+export function standingAmongHumans(contributors: readonly ContributorEntry[], login: string): { commits: number; rank: number } {
+    const humans = contributors.filter(contributor => !isBot(contributor)).sort((left, right) => right.contributions - left.contributions);
+    const index = humans.findIndex(contributor => contributor.login.toLowerCase() === login.toLowerCase());
+    return index < 0 ? { commits: 0, rank: 0 } : { commits: humans[index]!.contributions, rank: index + 1 };
+}
+
+/**
+ * Turns search nodes into the feed: merged, public only (the token may see private work, the site never
+ * shows it), newest first, capped at `limit`.
+ */
+export function parseMergedPullRequests(nodes: readonly PullRequestNode[], limit: number): PullRequest[] {
+    return nodes
+        .filter((node): node is NonNullable<PullRequestNode> => !!node?.mergedAt && node.repository?.isPrivate === false && !!node.url && node.number !== undefined)
+        .sort((left, right) => right.mergedAt!.localeCompare(left.mergedAt!))
+        .slice(0, limit)
+        .map(node => ({
+            title: node.title ?? '',
+            repository: node.repository!.nameWithOwner ?? `${node.repository!.owner?.login ?? ''}/${node.repository!.name ?? ''}`,
+            number: node.number!,
+            url: node.url!,
+            mergedAt: node.mergedAt!,
+        }));
+}
+
+/** A contribution calendar as the GraphQL API returns it. */
+export type CalendarWeekNode = { contributionDays: { date: string; contributionCount: number }[] };
+
+/** Compacts the calendar into week starts and daily counts. */
+export const parseCalendar = (weeks: readonly CalendarWeekNode[]): ContributionWeek[] =>
+    weeks.filter(week => week.contributionDays.length > 0).map(week => ({
+        start: week.contributionDays[0]!.date,
+        counts: week.contributionDays.map(day => day.contributionCount),
+    }));
+
+/** The search query for merged public pull requests by `login` in any of `orgs`. */
+export const mergedPullRequestQuery = (login: string, orgs: readonly string[]): string =>
+    `author:${login} ${orgs.map(org => `org:${org}`).join(' ')} is:public is:pr is:merged`;

package/index.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import sitemap from '@astrojs/sitemap';
+import tailwindcss from '@tailwindcss/vite';
+import type { AstroIntegration } from 'astro';
+import type { CastData } from './integration/CastData';
+import type { CastOptions } from './integration/CastOptions';
+import { resolveData } from './integration/resolveData';
+import { castVirtualModule } from './integration/virtualModule';
+
+export type { CastOptions } from './integration/CastOptions';
+export type { CastData } from './integration/CastData';
+export * from './config/index';
+export * from './badges/index';
+
+const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL('./package.json', import.meta.url)), 'utf8')) as { version: string };
+
+/** The pages and files every Cast site serves. */
+const routes: [pattern: string, entrypoint: string][] = [
+    ['/', 'index.astro'],
+    ['/cv', 'cv.astro'],
+    ['/404', '404.astro'],
+    ['/cast.json', 'cast.json.ts'],
+    ['/resume.json', 'resume.json.ts'],
+    ['/llms.txt', 'llms.txt.ts'],
+    ['/badge.svg', 'badge.svg.ts'],
+    ['/badge-card.svg', 'badge-card.svg.ts'],
+    ['/og.png', 'og.png.ts'],
+    ['/favicon.svg', 'favicon.svg.ts'],
+    ['/apple-touch-icon.png', 'apple-touch-icon.png.ts'],
+    ['/robots.txt', 'robots.txt.ts'],
+];
+
+/**
+ * The Cast integration. Reads cast.yaml, captures public GitHub and writing data at build time, verifies the
+ * tier against the Cast registry and injects every page. Tailwind, fonts and the sitemap are configured here,
+ * so a site needs nothing but `integrations: [cast()]`.
+ */
+export default function cast(options: CastOptions = {}): AstroIntegration {
+    let data: CastData | undefined;
+    let photoFile: string | undefined;
+
+    return {
+        name: '@cratis/cast',
+        hooks: {
+            'astro:config:setup': async ({ config, command, updateConfig, injectRoute, addWatchFile, logger }) => {
+                const root = fileURLToPath(config.root);
+                const configFile = path.resolve(root, options.config ?? 'cast.yaml');
+                const snapshotFile = path.resolve(root, options.snapshot ?? '.cast/snapshot.json');
+                const fetchMode = options.fetch ?? 'build';
+                addWatchFile(configFile);
+
+                const resolved = await resolveData({
+                    configFile,
+                    snapshotFile,
+                    fetch: fetchMode === 'always' || (fetchMode === 'build' && command === 'build'),
+                    castVersion: packageJson.version,
+                    log: logger,
+                });
+                data = resolved.data;
+                photoFile = resolved.photoFile;
+                const site = data.config.site.url;
+                logger.info(`${data.config.person.name} (@${data.config.person.handle}): tier ${data.tier.tier ?? 'none'} from ${data.tier.source}`);
+
+                for (const [pattern, entrypoint] of routes) {
+                    injectRoute({ pattern, entrypoint: `@cratis/cast/routes/${entrypoint}`, prerender: true });
+                }
+
+                updateConfig({
+                    site: config.site ?? site,
+                    trailingSlash: 'ignore',
+                    redirects: { '/resume': '/cv', ...config.redirects },
+                    integrations: [sitemap({ filter: page => !page.endsWith('/404/') && !page.endsWith('/404') })],
+                    vite: {
+                        plugins: [
+                            tailwindcss(),
+                            castVirtualModule(() => data!, () => photoFile),
+                        ],
+                    },
+                } as Parameters<typeof updateConfig>[0]);
+            },
+        },
+    };
+}

package/integration/CastData.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ResolvedTier } from '../badges/ResolvedTier';
+import type { CastConfig } from '../config/CastConfig';
+import type { ResolvedSection } from '../config/ResolvedSection';
+import type { GitHubSnapshot } from '../github/GitHubSnapshot';
+import type { WritingSnapshot } from '../writing/WritingSnapshot';
+
+/** Everything the site renders from, resolved once per build and served through `virtual:cast`. */
+export type CastData = {
+    config: CastConfig;
+    sections: ResolvedSection[];
+    github: GitHubSnapshot;
+    writing: WritingSnapshot;
+    tier: ResolvedTier;
+    /** Remote portrait URL, when `person.photo` is an https URL. */
+    photoUrl?: string;
+    build: { builtAt: string; castVersion: string; githubSource: 'live' | 'snapshot' | 'none'; registrySource: 'live' | 'bundled' };
+};

package/integration/CastOptions.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Options for the `cast()` integration. */
+export type CastOptions = {
+    /** Path to cast.yaml, relative to the project root. Defaults to `./cast.yaml`. */
+    config?: string;
+
+    /** Where the last good build-time data is kept, relative to the project root. Defaults to `./.cast/snapshot.json`. */
+    snapshot?: string;
+
+    /**
+     * When to fetch GitHub, writing and registry data. `build` (the default) fetches on `astro build` only;
+     * `always` also fetches when the dev server starts; `never` uses the snapshot only.
+     */
+    fetch?: 'build' | 'always' | 'never';
+};

package/integration/Snapshot.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { GitHubSnapshot } from '../github/GitHubSnapshot';
+import type { WritingSnapshot } from '../writing/WritingSnapshot';
+
+/** The file at `.cast/snapshot.json`: the last data that was captured successfully. */
+export type Snapshot = {
+    version: 1;
+    github?: GitHubSnapshot;
+    writing?: WritingSnapshot;
+};

package/integration/loadRegistry.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { registryUrl } from '../badges/constants';
+import { parseRegistry } from '../badges/registry';
+import type { RegistryMember } from '../badges/RegistryMember';
+
+/** The registry copy bundled into the package when it is published. */
+export const bundledRegistryFile = fileURLToPath(new URL('../registry/members.yaml', import.meta.url));
+
+/** Reads the bundled registry; an absent copy is an empty registry. */
+export async function readBundledRegistry(): Promise<RegistryMember[]> {
+    try {
+        return parseRegistry(await readFile(bundledRegistryFile, 'utf8'));
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Reads the reviewed registry from the Cast repository, falling back to the bundled copy. A registry that
+ * fails validation is never used.
+ */
+export async function loadRegistry(fetchLive: boolean, warn: (message: string) => void): Promise<{ members: RegistryMember[]; source: 'live' | 'bundled' }> {
+    if (fetchLive) {
+        try {
+            const response = await fetch(registryUrl, { headers: { 'user-agent': 'cratis-cast-build' }, signal: AbortSignal.timeout(15_000) });
+            if (!response.ok) throw new Error(`answered ${response.status}`);
+            return { members: parseRegistry(await response.text()), source: 'live' };
+        } catch (error) {
+            warn(`registry: ${error instanceof Error ? error.message : String(error)}; using the bundled copy`);
+        }
+    }
+    return { members: await readBundledRegistry(), source: 'bundled' };
+}

package/integration/resolveData.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { cratisOrganization } from '../badges/constants';
+import { resolveTier } from '../badges/resolveTier';
+import type { RegistryMember } from '../badges/RegistryMember';
+import type { ResolvedTier } from '../badges/ResolvedTier';
+import type { GitHubSnapshot } from '../github/GitHubSnapshot';
+import type { CastConfig } from '../config/CastConfig';
+import { parseCast } from '../config/parseCast';
+import { resolveSections } from '../config/resolveSections';
+import { fetchGitHub, gitHubToken, type FreshEvidence } from '../github/fetchGitHub';
+import { emptySnapshot } from '../github/GitHubSnapshot';
+import { fetchWriting } from '../writing/fetchWriting';
+import type { CastData } from './CastData';
+import { loadRegistry } from './loadRegistry';
+import { readSnapshot, writeSnapshot } from './snapshotFile';
+
+/** Inputs for one resolution. */
+export type ResolveDataOptions = {
+    configFile: string;
+    snapshotFile: string;
+    fetch: boolean;
+    castVersion: string;
+    log: { info(message: string): void; warn(message: string): void };
+};
+
+/** Result of a resolution: the data plus the absolute path of a local portrait, if any. */
+export type ResolvedCast = { data: CastData; photoFile?: string };
+
+/** owner/name of every public Cratis repository the cratis section lists. */
+export const trackedCratisRepositories = (config: CastConfig): string[] =>
+    (config.cratis?.repos ?? [])
+        .filter(repository => repository.url?.toLowerCase().startsWith(`https://github.com/${cratisOrganization.toLowerCase()}/`))
+        .map(repository => `${cratisOrganization}/${repository.name}`);
+
+const sameLogin = (left: string, right: string): boolean => left.toLowerCase() === right.toLowerCase();
+
+/** The snapshot's GitHub data, only when it was captured for this identity. */
+export const usableSnapshot = (github: GitHubSnapshot | undefined, identity: string): GitHubSnapshot | undefined =>
+    github && typeof github.login === 'string' && sameLogin(github.login, identity) ? github : undefined;
+
+/**
+ * The tier a site shows: a claim, linked to the directory, which is the authority. Core and Partner come from
+ * the registry by the GitHub login. Contributor comes only from `freshCratisMergedPullRequests`: the count a
+ * search returned in this build for that login. It is never read from a snapshot and never persisted.
+ */
+export function siteTier(identity: string, registry: readonly RegistryMember[], freshCratisMergedPullRequests: number | undefined): ResolvedTier {
+    return resolveTier(identity, registry, freshCratisMergedPullRequests);
+}
+
+/**
+ * Reads cast.yaml, captures build-time data (never failing the build on network problems) and resolves the
+ * verified tier. Order of truth for live data: a fresh fetch, then `.cast/snapshot.json`, then cast.yaml.
+ */
+export async function resolveData(options: ResolveDataOptions): Promise<ResolvedCast> {
+    const configText = await readFile(options.configFile, 'utf8');
+    const config = parseCast(configText, path.basename(options.configFile));
+    const warn = (message: string) => options.log.warn(`${message}`);
+
+    const identity = config.github.login;
+    const snapshot = await readSnapshot(options.snapshotFile);
+    const snapshotGitHub = usableSnapshot(snapshot.github, identity);
+    if (snapshot.github && !snapshotGitHub) {
+        warn(`.cast/snapshot.json holds GitHub data for '${snapshot.github.login}', not '${identity}'; ignoring it`);
+    }
+    let github = snapshotGitHub;
+    let githubSource: CastData['build']['githubSource'] = github ? 'snapshot' : 'none';
+    let writing = snapshot.writing;
+    let changed = false;
+    let freshEvidence: FreshEvidence = {};
+
+    if (options.fetch) {
+        const token = gitHubToken();
+        if (!token) {
+            warn('no GITHUB_TOKEN or GH_TOKEN in the environment; using the snapshot for GitHub data');
+        } else {
+            const result = await fetchGitHub({
+                login: config.github.login,
+                orgs: config.github.orgs,
+                repositories: trackedCratisRepositories(config),
+                releases: config.github.releases,
+                stars: config.github.stars,
+            }, token, github, warn);
+            const fresh = result?.snapshot;
+            if (fresh && !sameLogin(fresh.login, identity)) {
+                warn(`GitHub answered for '${fresh.login}', not '${identity}'; ignoring it`);
+            } else if (result && fresh) {
+                github = fresh;
+                freshEvidence = result.fresh;
+                githubSource = 'live';
+                changed = true;
+                options.log.info(`GitHub: ${fresh.contributions.total} contributions, ${fresh.mergedPullRequests.total} merged pull requests, ${Object.keys(fresh.repositories).length} repositories`);
+            }
+        }
+        if (config.writing.sources.length > 0) {
+            const freshWriting = await fetchWriting(config.writing.sources, warn);
+            if (freshWriting) {
+                writing = freshWriting;
+                changed = true;
+                options.log.info(`writing: ${freshWriting.posts.length} posts`);
+            } else {
+                warn('no posts captured; using the snapshot for writing');
+            }
+        }
+    }
+
+    if (changed) {
+        await writeSnapshot(options.snapshotFile, { version: 1, github, writing });
+    }
+
+    const registry = await loadRegistry(options.fetch, warn);
+    const githubData = github ?? emptySnapshot(identity, config.github.orgs);
+    const tier = siteTier(identity, registry.members, freshEvidence.cratisMergedPullRequests);
+
+    const photo = config.person.photo;
+    const photoUrl = photo && /^https:\/\//.test(photo) ? photo : undefined;
+    const localPhoto = photo && !photoUrl ? path.resolve(path.dirname(options.configFile), photo) : undefined;
+    if (localPhoto && !existsSync(localPhoto)) {
+        warn(`person.photo: ${localPhoto} does not exist; the portrait is left out`);
+    }
+
+    return {
+        data: {
+            config,
+            sections: resolveSections(config),
+            github: githubData,
+            writing: writing ?? { sources: [], posts: [] },
+            tier,
+            photoUrl: photoUrl ?? (localPhoto ? undefined : githubData.profile?.avatarUrl),
+            build: { builtAt: new Date().toISOString(), castVersion: options.castVersion, githubSource, registrySource: registry.source },
+        },
+        photoFile: localPhoto && existsSync(localPhoto) ? localPhoto : undefined,
+    };
+}

package/integration/snapshotFile.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { Snapshot } from './Snapshot';
+
+/** Reads the snapshot; a missing or unreadable file is an empty snapshot. */
+export async function readSnapshot(file: string): Promise<Snapshot> {
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf8')) as Snapshot;
+        return parsed && typeof parsed === 'object' ? { ...parsed, version: 1 } : { version: 1 };
+    } catch {
+        return { version: 1 };
+    }
+}
+
+/** Writes the snapshot with per-week count arrays on one line so diffs stay readable. */
+export async function writeSnapshot(file: string, snapshot: Snapshot): Promise<void> {
+    await mkdir(path.dirname(file), { recursive: true });
+    const json = JSON.stringify(snapshot, null, 2).replace(/\[\s*(\d[\d,\s]*?)\s*\]/g, (_, numbers: string) => `[${numbers.split(/[\s,]+/).join(', ')}]`);
+    await writeFile(file, `${json}\n`);
+}