diff --git a/gitgram/backend/src/controllers/githubController.ts b/gitgram/backend/src/controllers/githubController.ts index 8e17bd80..7198141b 100644 --- a/gitgram/backend/src/controllers/githubController.ts +++ b/gitgram/backend/src/controllers/githubController.ts @@ -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) => { diff --git a/gitgram/backend/src/services/githubContributionsService.ts b/gitgram/backend/src/services/githubContributionsService.ts new file mode 100644 index 00000000..8201134b --- /dev/null +++ b/gitgram/backend/src/services/githubContributionsService.ts @@ -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; +} + +// --------------------------------------------------------------------------- +// 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 | 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(); + + 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) => Promise; + +export interface HarvestDb { + user: { findUnique: (args: unknown) => Promise<{ githubAccessToken: string | null; githubUsername: string | null } | null> }; + repositoryManager: { findMany: (args: unknown) => Promise> }; + 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 { + 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(); + 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(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 }; +} diff --git a/gitgram/backend/tests/githubContributions.test.ts b/gitgram/backend/tests/githubContributions.test.ts new file mode 100644 index 00000000..11f18b2d --- /dev/null +++ b/gitgram/backend/tests/githubContributions.test.ts @@ -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([ + ['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>((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 = {}): { 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(); + }); +});