feat(talent): backfill real contribution evidence via GraphQL at sync time

The talent graph's `github_activity` evidence was written only by the GitHub
App webhook, so a new user's contribution-trajectory evidence stayed empty
until an owner configured a webhook and it fired — an ops dependency, not real
first-run data. Backfill it from the GitHub GraphQL contributionsCollection.

- githubContributionsService: pure `mapContributionsToActivities` turns real
  commit/PR/review/issue contributions into RepositoryActivity rows, scoped to
  the user's managed repositories (RepositoryManager), attributed to their
  GitHub identity (actorLogin), deduped by a deterministic eventId that mirrors
  the webhook delivery-id discipline. `harvestContributionEvidence` fetches via
  octokit.graphql (no new dependency) and deduped-inserts with skipDuplicates.
  Injectable db + graphql client so it is unit tested without Postgres/GitHub.
- githubController.syncProjects: run the backfill after project sync, non-fatal
  (a harvest failure never breaks the primary sync), and report the counts.

This makes contribution evidence real and immediate after login with no
GitHub-App-webhook ops dependency and no fabricated seed data.

Tests: mapping (all 4 contribution types), managed-repo scoping, identity
attribution, deterministic-id dedupe, malformed/empty input, and the harvester
no-op / happy-path / graphql-failure paths. 20 new assertions across 10 tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
caelum0x 2026-09-06 10:35:09 +03:00
parent 2c4ce3a651
commit 2431ac08f9
3 changed files with 555 additions and 1 deletions

View File

@ -11,6 +11,7 @@ import { getCachedProfile, setCachedProfile, setCachedRepo } from '../utils/gith
import { fetchGitHubTrending } from '../services/ghSocialBridge'
import { GitHubService } from '../services/githubService'
import { createNotification } from '../services/notificationService'
import { harvestContributionEvidence } from '../services/githubContributionsService'
/**
* Resolve the authenticated user's stored GitHub OAuth token, or throw a
@ -95,7 +96,17 @@ export const githubController = {
})
}
res.json({ message: 'Projects synced', count: repos.length })
// Backfill real talent-graph contribution evidence for the user's claimed
// repositories from the GitHub GraphQL contributionsCollection. Non-fatal:
// a failure here must never break the primary project sync.
let contributionEvidence = { scannedRepositories: 0, mapped: 0, created: 0 }
try {
contributionEvidence = await harvestContributionEvidence(userId)
} catch (error) {
logger.warn('syncProjects: contribution evidence backfill failed', error)
}
res.json({ message: 'Projects synced', count: repos.length, contributionEvidence })
}),
getProjects: asyncHandler(async (req: AuthRequest, res: Response) => {

View File

@ -0,0 +1,333 @@
/**
* GitHub contributions harvester (talent-graph evidence backfill).
*
* The talent graph derives `github_activity` evidence from `RepositoryActivity`
* rows. Until now those rows were written ONLY by the GitHub App webhook
* (githubActivityService.processGitHubEvent), so a brand-new user's
* contribution-trajectory evidence was empty until an owner configured a
* webhook and it fired — an operational dependency, not real data at first run.
*
* This service backfills genuine contribution evidence at sync time using the
* GitHub GraphQL `contributionsCollection` (real commits / PRs / reviews /
* issues the user actually made). It is:
* - Real, never fabricated — every row maps to an actual GitHub contribution.
* - Scoped to the user's *managed* repositories (RepositoryManager), so it
* only produces evidence the talent graph will surface, and never invents
* Repository rows.
* - Attributed to the user's GitHub identity (actorLogin = githubUsername),
* which is exactly what the evidence query filters on.
* - Deduped by a deterministic `eventId`, mirroring the delivery-id
* idempotency discipline the webhook path uses, so re-syncing is a no-op.
*
* The mapping (`mapContributionsToActivities`) is pure and dependency-injected
* so it can be unit tested without a live Postgres or GitHub.
*/
import { Octokit } from '@octokit/rest';
import { GitHubEventType, Prisma } from '@prisma/client';
import prisma from '../utils/prisma';
import logger from '../utils/logger';
// ---------------------------------------------------------------------------
// GraphQL response shapes (only the fields we consume; external data)
// ---------------------------------------------------------------------------
interface ContribRepoRef {
nameWithOwner: string;
url?: string | null;
}
interface CommitContributionsByRepository {
repository: ContribRepoRef;
contributions: { nodes: Array<{ occurredAt: string; commitCount: number } | null> };
}
interface PullRequestContributionsByRepository {
repository: ContribRepoRef;
contributions: {
nodes: Array<{
pullRequest: { id: string; number: number; title: string; url: string; createdAt: string; merged: boolean } | null;
} | null>;
};
}
interface PullRequestReviewContributionsByRepository {
repository: ContribRepoRef;
contributions: {
nodes: Array<{
occurredAt?: string | null;
pullRequestReview: { id: string; url?: string | null; submittedAt?: string | null } | null;
pullRequest: { number: number; title: string; url?: string | null } | null;
} | null>;
};
}
interface IssueContributionsByRepository {
repository: ContribRepoRef;
contributions: {
nodes: Array<{
issue: { id: string; number: number; title: string; url: string; createdAt: string } | null;
} | null>;
};
}
export interface ContributionsCollection {
commitContributionsByRepository?: CommitContributionsByRepository[] | null;
pullRequestContributionsByRepository?: PullRequestContributionsByRepository[] | null;
pullRequestReviewContributionsByRepository?: PullRequestReviewContributionsByRepository[] | null;
issueContributionsByRepository?: IssueContributionsByRepository[] | null;
}
export interface ContributionsResponse {
user: { contributionsCollection: ContributionsCollection | null } | null;
}
export interface MapContributionsContext {
/** The GitHub login these contributions belong to (evidence attribution). */
githubUsername: string;
/** Managed repository ids keyed by lowercased `owner/name`. */
repoIdByFullName: ReadonlyMap<string, string>;
}
// ---------------------------------------------------------------------------
// GraphQL query
// ---------------------------------------------------------------------------
export const CONTRIBUTIONS_QUERY = `
query ContributionEvidence($login: String!) {
user(login: $login) {
contributionsCollection {
commitContributionsByRepository(maxRepositories: 100) {
repository { nameWithOwner url }
contributions(first: 100) { nodes { occurredAt commitCount } }
}
pullRequestContributionsByRepository(maxRepositories: 100) {
repository { nameWithOwner url }
contributions(first: 50) { nodes { pullRequest { id number title url createdAt merged } } }
}
pullRequestReviewContributionsByRepository(maxRepositories: 100) {
repository { nameWithOwner url }
contributions(first: 50) { nodes { occurredAt pullRequestReview { id url submittedAt } pullRequest { number title url } } }
}
issueContributionsByRepository(maxRepositories: 100) {
repository { nameWithOwner url }
contributions(first: 50) { nodes { issue { id number title url createdAt } } }
}
}
}
}
`;
// ---------------------------------------------------------------------------
// Pure mapping: contributionsCollection -> RepositoryActivity create inputs
// ---------------------------------------------------------------------------
function resolveRepoId(
repository: ContribRepoRef | undefined,
repoIdByFullName: ReadonlyMap<string, string>,
): string | null {
const fullName = repository?.nameWithOwner;
if (!fullName) return null;
return repoIdByFullName.get(fullName.toLowerCase()) ?? null;
}
/**
* Maps a GraphQL `contributionsCollection` into RepositoryActivity create
* inputs, restricted to the user's managed repositories. Pure and deterministic:
* - only contributions to a managed repository are emitted;
* - `actorLogin` is always the user (attribution the evidence query needs);
* - `eventId` is a stable, content-derived key so re-runs dedupe cleanly.
*/
export function mapContributionsToActivities(
collection: ContributionsCollection | null | undefined,
ctx: MapContributionsContext,
): Prisma.RepositoryActivityCreateManyInput[] {
if (!collection) return [];
const actorLogin = ctx.githubUsername;
const rows: Prisma.RepositoryActivityCreateManyInput[] = [];
const seenEventIds = new Set<string>();
const push = (row: Prisma.RepositoryActivityCreateManyInput): void => {
if (seenEventIds.has(row.eventId)) return;
seenEventIds.add(row.eventId);
rows.push(row);
};
// Commits — aggregated per repository into day buckets by the API.
for (const entry of collection.commitContributionsByRepository ?? []) {
const repositoryId = resolveRepoId(entry?.repository, ctx.repoIdByFullName);
if (!repositoryId) continue;
const url = entry.repository.url ?? null;
for (const node of entry.contributions?.nodes ?? []) {
if (!node || !node.occurredAt || !node.commitCount) continue;
const commitCount = node.commitCount;
push({
repositoryId,
eventType: GitHubEventType.PUSH,
eventId: `contrib:commit:${repositoryId}:${node.occurredAt}`,
action: 'contributed',
actorLogin,
title: `Contributed ${commitCount} commit${commitCount === 1 ? '' : 's'}`,
url,
occurredAt: new Date(node.occurredAt),
metadata: { source: 'contributionsCollection', kind: 'commit', commitCount },
});
}
}
// Pull requests authored.
for (const entry of collection.pullRequestContributionsByRepository ?? []) {
const repositoryId = resolveRepoId(entry?.repository, ctx.repoIdByFullName);
if (!repositoryId) continue;
for (const node of entry.contributions?.nodes ?? []) {
const pr = node?.pullRequest;
if (!pr || !pr.id || !pr.createdAt) continue;
push({
repositoryId,
eventType: GitHubEventType.PULL_REQUEST,
eventId: `contrib:pr:${pr.id}`,
action: pr.merged ? 'merged' : 'opened',
actorLogin,
title: `Opened PR #${pr.number}: ${pr.title}`,
url: pr.url ?? null,
occurredAt: new Date(pr.createdAt),
metadata: { source: 'contributionsCollection', kind: 'pull_request', number: pr.number, merged: pr.merged },
});
}
}
// Pull request reviews.
for (const entry of collection.pullRequestReviewContributionsByRepository ?? []) {
const repositoryId = resolveRepoId(entry?.repository, ctx.repoIdByFullName);
if (!repositoryId) continue;
for (const node of entry.contributions?.nodes ?? []) {
const review = node?.pullRequestReview;
const occurredAt = node?.occurredAt ?? review?.submittedAt;
if (!review || !review.id || !occurredAt) continue;
const number = node?.pullRequest?.number;
push({
repositoryId,
eventType: GitHubEventType.PULL_REQUEST,
eventId: `contrib:review:${review.id}`,
action: 'reviewed',
actorLogin,
title: number != null ? `Reviewed PR #${number}` : 'Reviewed a pull request',
url: review.url ?? node?.pullRequest?.url ?? null,
occurredAt: new Date(occurredAt),
metadata: { source: 'contributionsCollection', kind: 'pull_request_review', number: number ?? null },
});
}
}
// Issues opened.
for (const entry of collection.issueContributionsByRepository ?? []) {
const repositoryId = resolveRepoId(entry?.repository, ctx.repoIdByFullName);
if (!repositoryId) continue;
for (const node of entry.contributions?.nodes ?? []) {
const issue = node?.issue;
if (!issue || !issue.id || !issue.createdAt) continue;
push({
repositoryId,
eventType: GitHubEventType.ISSUES,
eventId: `contrib:issue:${issue.id}`,
action: 'opened',
actorLogin,
title: `Opened issue #${issue.number}: ${issue.title}`,
url: issue.url ?? null,
occurredAt: new Date(issue.createdAt),
metadata: { source: 'contributionsCollection', kind: 'issue', number: issue.number },
});
}
}
return rows;
}
// ---------------------------------------------------------------------------
// Harvester (GraphQL fetch + deduped insert)
// ---------------------------------------------------------------------------
export type GraphqlClient = (query: string, variables: Record<string, unknown>) => Promise<ContributionsResponse>;
export interface HarvestDb {
user: { findUnique: (args: unknown) => Promise<{ githubAccessToken: string | null; githubUsername: string | null } | null> };
repositoryManager: { findMany: (args: unknown) => Promise<Array<{ repository: { id: string; fullName: string } }>> };
repositoryActivity: { createMany: (args: { data: Prisma.RepositoryActivityCreateManyInput[]; skipDuplicates?: boolean }) => Promise<{ count: number }> };
}
export interface HarvestDeps {
db?: HarvestDb;
graphqlClient?: GraphqlClient;
}
export interface HarvestResult {
scannedRepositories: number;
mapped: number;
created: number;
}
/**
* Backfills contribution evidence for a user's managed repositories. Safe to
* call on every sync: it is a no-op when the user has no linked GitHub token,
* no GitHub username, or no managed repositories, and inserts are deduped by
* the deterministic contribution eventId.
*/
export async function harvestContributionEvidence(
userId: string,
deps: HarvestDeps = {},
): Promise<HarvestResult> {
const db = deps.db ?? (prisma as unknown as HarvestDb);
const empty: HarvestResult = { scannedRepositories: 0, mapped: 0, created: 0 };
const user = await db.user.findUnique({
where: { id: userId },
select: { githubAccessToken: true, githubUsername: true },
});
if (!user?.githubAccessToken || !user.githubUsername) return empty;
const managed = await db.repositoryManager.findMany({
where: { userId },
select: { repository: { select: { id: true, fullName: true } } },
});
if (managed.length === 0) return empty;
const repoIdByFullName = new Map<string, string>();
for (const manager of managed) {
if (manager.repository?.fullName && manager.repository.id) {
repoIdByFullName.set(manager.repository.fullName.toLowerCase(), manager.repository.id);
}
}
if (repoIdByFullName.size === 0) return empty;
const graphqlClient: GraphqlClient =
deps.graphqlClient ??
((query, variables) =>
new Octokit({ auth: user.githubAccessToken! }).graphql<ContributionsResponse>(query, variables));
let response: ContributionsResponse;
try {
response = await graphqlClient(CONTRIBUTIONS_QUERY, { login: user.githubUsername });
} catch (error) {
logger.warn('[contributions] GraphQL harvest failed', { userId, error });
return { ...empty, scannedRepositories: repoIdByFullName.size };
}
const activities = mapContributionsToActivities(response?.user?.contributionsCollection, {
githubUsername: user.githubUsername,
repoIdByFullName,
});
if (activities.length === 0) {
return { scannedRepositories: repoIdByFullName.size, mapped: 0, created: 0 };
}
const result = await db.repositoryActivity.createMany({ data: activities, skipDuplicates: true });
logger.info('[contributions] Backfilled contribution evidence', {
userId,
scannedRepositories: repoIdByFullName.size,
mapped: activities.length,
created: result.count,
});
return { scannedRepositories: repoIdByFullName.size, mapped: activities.length, created: result.count };
}

View File

@ -0,0 +1,210 @@
import { GitHubEventType } from '@prisma/client';
import {
mapContributionsToActivities,
harvestContributionEvidence,
type ContributionsCollection,
type ContributionsResponse,
type HarvestDb,
} from '../src/services/githubContributionsService';
/**
* Unit tests for the talent-graph contribution-evidence backfill. These lock in
* the properties the evidence layer depends on:
* - only contributions to *managed* repositories become evidence;
* - every row is attributed to the user's GitHub identity (actorLogin);
* - re-runs dedupe via a deterministic eventId;
* - the harvest is a safe no-op without a token / username / managed repos.
*/
const repoIdByFullName = new Map<string, string>([
['octocat/hello-world', 'repo-1'],
['octocat/spoon-knife', 'repo-2'],
]);
const ctx = { githubUsername: 'octocat', repoIdByFullName } as const;
function sampleCollection(): ContributionsCollection {
return {
commitContributionsByRepository: [
{
repository: { nameWithOwner: 'octocat/Hello-World', url: 'https://github.com/octocat/Hello-World' },
contributions: { nodes: [{ occurredAt: '2026-09-01T00:00:00Z', commitCount: 3 }] },
},
// Not a managed repository — must be skipped.
{
repository: { nameWithOwner: 'stranger/repo', url: 'https://github.com/stranger/repo' },
contributions: { nodes: [{ occurredAt: '2026-09-02T00:00:00Z', commitCount: 9 }] },
},
],
pullRequestContributionsByRepository: [
{
repository: { nameWithOwner: 'octocat/spoon-knife', url: 'https://github.com/octocat/spoon-knife' },
contributions: {
nodes: [
{ pullRequest: { id: 'PR_1', number: 42, title: 'Add feature', url: 'https://github.com/octocat/spoon-knife/pull/42', createdAt: '2026-08-20T00:00:00Z', merged: true } },
{ pullRequest: null },
],
},
},
],
pullRequestReviewContributionsByRepository: [
{
repository: { nameWithOwner: 'octocat/hello-world', url: 'https://github.com/octocat/hello-world' },
contributions: {
nodes: [
{ occurredAt: '2026-08-21T00:00:00Z', pullRequestReview: { id: 'PRR_1', url: 'https://github.com/octocat/hello-world/pull/7#review', submittedAt: '2026-08-21T00:00:00Z' }, pullRequest: { number: 7, title: 'Fix bug', url: 'https://github.com/octocat/hello-world/pull/7' } },
],
},
},
],
issueContributionsByRepository: [
{
repository: { nameWithOwner: 'octocat/hello-world', url: 'https://github.com/octocat/hello-world' },
contributions: {
nodes: [
{ issue: { id: 'I_1', number: 5, title: 'Crash on load', url: 'https://github.com/octocat/hello-world/issues/5', createdAt: '2026-08-15T00:00:00Z' } },
],
},
},
],
};
}
describe('mapContributionsToActivities', () => {
it('maps commit, PR, review, and issue contributions for managed repositories', () => {
const rows = mapContributionsToActivities(sampleCollection(), ctx);
const byType = rows.reduce<Record<string, number>>((acc, row) => {
acc[row.eventType] = (acc[row.eventType] ?? 0) + 1;
return acc;
}, {});
// 1 commit-day (managed) + 1 PR + 1 review (both PULL_REQUEST) + 1 issue.
expect(byType[GitHubEventType.PUSH]).toBe(1);
expect(byType[GitHubEventType.PULL_REQUEST]).toBe(2);
expect(byType[GitHubEventType.ISSUES]).toBe(1);
});
it('skips contributions to repositories the user does not manage', () => {
const rows = mapContributionsToActivities(sampleCollection(), ctx);
// The "stranger/repo" commit contribution (9 commits) must not appear.
expect(rows.some((row) => row.repositoryId !== 'repo-1' && row.repositoryId !== 'repo-2')).toBe(false);
expect(rows.find((row) => row.eventType === GitHubEventType.PUSH)?.repositoryId).toBe('repo-1');
});
it('attributes every row to the user GitHub identity (evidence query filter)', () => {
const rows = mapContributionsToActivities(sampleCollection(), ctx);
expect(rows.length).toBeGreaterThan(0);
expect(rows.every((row) => row.actorLogin === 'octocat')).toBe(true);
});
it('produces deterministic eventIds and dedupes repeated contribution nodes', () => {
const collection = sampleCollection();
// Duplicate the same PR node — the API can surface the same contribution twice.
collection.pullRequestContributionsByRepository![0].contributions.nodes.push({
pullRequest: { id: 'PR_1', number: 42, title: 'Add feature', url: 'https://x', createdAt: '2026-08-20T00:00:00Z', merged: true },
});
const rows = mapContributionsToActivities(collection, ctx);
const prRows = rows.filter((row) => row.eventId === 'contrib:pr:PR_1');
expect(prRows).toHaveLength(1);
expect(prRows[0].action).toBe('merged');
const ids = rows.map((row) => row.eventId);
expect(new Set(ids).size).toBe(ids.length);
});
it('returns an empty list for a null / empty collection', () => {
expect(mapContributionsToActivities(null, ctx)).toEqual([]);
expect(mapContributionsToActivities(undefined, ctx)).toEqual([]);
expect(mapContributionsToActivities({}, ctx)).toEqual([]);
});
it('skips malformed nodes (missing ids or timestamps)', () => {
const collection: ContributionsCollection = {
commitContributionsByRepository: [
{
repository: { nameWithOwner: 'octocat/hello-world', url: null },
contributions: { nodes: [null, { occurredAt: '', commitCount: 0 }] },
},
],
issueContributionsByRepository: [
{
repository: { nameWithOwner: 'octocat/hello-world', url: null },
contributions: { nodes: [{ issue: null }] },
},
],
};
expect(mapContributionsToActivities(collection, ctx)).toEqual([]);
});
});
describe('harvestContributionEvidence', () => {
function makeDb(overrides: Partial<HarvestDb> = {}): { db: HarvestDb; createMany: jest.Mock } {
const createMany = jest.fn().mockResolvedValue({ count: 4 });
const db: HarvestDb = {
user: { findUnique: jest.fn().mockResolvedValue({ githubAccessToken: 'gho_x', githubUsername: 'octocat' }) },
repositoryManager: {
findMany: jest.fn().mockResolvedValue([
{ repository: { id: 'repo-1', fullName: 'octocat/Hello-World' } },
{ repository: { id: 'repo-2', fullName: 'octocat/spoon-knife' } },
]),
},
repositoryActivity: { createMany },
...overrides,
};
return { db, createMany };
}
it('is a no-op when the user has no GitHub token', async () => {
const { db, createMany } = makeDb({
user: { findUnique: jest.fn().mockResolvedValue({ githubAccessToken: null, githubUsername: 'octocat' }) },
});
const graphqlClient = jest.fn();
const result = await harvestContributionEvidence('user-1', { db, graphqlClient });
expect(result).toEqual({ scannedRepositories: 0, mapped: 0, created: 0 });
expect(graphqlClient).not.toHaveBeenCalled();
expect(createMany).not.toHaveBeenCalled();
});
it('is a no-op when the user manages no repositories', async () => {
const { db, createMany } = makeDb({
repositoryManager: { findMany: jest.fn().mockResolvedValue([]) },
});
const graphqlClient = jest.fn();
const result = await harvestContributionEvidence('user-1', { db, graphqlClient });
expect(result).toEqual({ scannedRepositories: 0, mapped: 0, created: 0 });
expect(graphqlClient).not.toHaveBeenCalled();
expect(createMany).not.toHaveBeenCalled();
});
it('harvests, maps to managed repos, and deduped-inserts real contribution evidence', async () => {
const { db, createMany } = makeDb();
const response: ContributionsResponse = { user: { contributionsCollection: sampleCollection() } };
const graphqlClient = jest.fn().mockResolvedValue(response);
const result = await harvestContributionEvidence('user-1', { db, graphqlClient });
expect(graphqlClient).toHaveBeenCalledWith(expect.stringContaining('contributionsCollection'), { login: 'octocat' });
expect(createMany).toHaveBeenCalledTimes(1);
const insertArg = createMany.mock.calls[0][0];
expect(insertArg.skipDuplicates).toBe(true);
// Only managed-repo rows are inserted (the stranger/repo commit is dropped).
expect(insertArg.data.every((row: { repositoryId: string }) => ['repo-1', 'repo-2'].includes(row.repositoryId))).toBe(true);
expect(result.scannedRepositories).toBe(2);
expect(result.created).toBe(4);
});
it('never throws when the GraphQL call fails', async () => {
const { db, createMany } = makeDb();
const graphqlClient = jest.fn().mockRejectedValue(new Error('rate limited'));
const result = await harvestContributionEvidence('user-1', { db, graphqlClient });
expect(result).toEqual({ scannedRepositories: 2, mapped: 0, created: 0 });
expect(createMany).not.toHaveBeenCalled();
});
});