From a4e1464ce5646e302c4ae7765983fbebb984caa4 Mon Sep 17 00:00:00 2001 From: caelum0x Date: Tue, 25 Aug 2026 03:42:36 +0300 Subject: [PATCH] feat: need-coverage / gap-analysis service + endpoint --- .../src/controllers/talentGraphController.ts | 10 ++ gitgram/backend/src/routes/talentGraph.ts | 1 + .../src/services/talentGapAnalysisService.ts | 157 ++++++++++++++++++ .../tests/unit/talentGapAnalysis.test.ts | 155 +++++++++++++++++ 4 files changed, 323 insertions(+) create mode 100644 gitgram/backend/src/services/talentGapAnalysisService.ts create mode 100644 gitgram/backend/tests/unit/talentGapAnalysis.test.ts diff --git a/gitgram/backend/src/controllers/talentGraphController.ts b/gitgram/backend/src/controllers/talentGraphController.ts index b6335344..58315e92 100644 --- a/gitgram/backend/src/controllers/talentGraphController.ts +++ b/gitgram/backend/src/controllers/talentGraphController.ts @@ -2,6 +2,7 @@ import type { Response } from 'express'; import type { AuthRequest } from '../middleware/auth'; import { asyncHandler, Errors } from '../middleware/errorHandler'; import { findTalentMatches, getTalentGraph } from '../services/talentGraphService'; +import { analyzeNeedCoverage } from '../services/talentGapAnalysisService'; import prisma from '../utils/prisma'; import { normalizePublicHttpUrl } from '../utils/publicHttpUrl'; import { runTalentMutation, type TalentMutationResult } from '../services/talentMutationService'; @@ -182,6 +183,15 @@ export const talentGraphController = { res.json({ data: { opportunity: publicOpportunity(opportunity, req.userId), matches } }); }), + getOpportunityCoverage: asyncHandler(async (req: AuthRequest, res: Response) => { + const opportunity = await prisma.talentOpportunity.findUnique({ where: { id: req.params.id } }); + if (!opportunity) throw Errors.notFound('Talent opportunity', req.params.id); + const matches = await findTalentMatches(opportunity.requiredSkills, 25); + const coverage = analyzeNeedCoverage(opportunity.requiredSkills, matches); + setViewerAwareReadCache(res, req.userId); + res.json({ data: { opportunity: publicOpportunity(opportunity, req.userId), coverage } }); + }), + startPilot: asyncHandler(async (req: AuthRequest, res: Response) => { const participantId = boundedText(req.body.participantId, 'participantId', 160); if (participantId === req.userId) throw Errors.badRequest('Opportunity owners cannot verify their own pilot evidence'); diff --git a/gitgram/backend/src/routes/talentGraph.ts b/gitgram/backend/src/routes/talentGraph.ts index 701e5023..3dabaaed 100644 --- a/gitgram/backend/src/routes/talentGraph.ts +++ b/gitgram/backend/src/routes/talentGraph.ts @@ -31,6 +31,7 @@ router.get('/public/:username', talentGraphController.getPublic); router.get('/opportunities', optionalAuth, talentGraphController.listOpportunities); router.post('/opportunities', authenticate, requireMutationOrigin, interactionLimiter, talentGraphController.createOpportunity); router.get('/opportunities/:id/matches', optionalAuth, talentGraphController.getOpportunityMatches); +router.get('/opportunities/:id/coverage', optionalAuth, talentGraphController.getOpportunityCoverage); router.post('/opportunities/:id/pilots', authenticate, requireMutationOrigin, interactionLimiter, talentGraphController.startPilot); router.post('/opportunities/:id/referrals', authenticate, requireMutationOrigin, interactionLimiter, talentGraphController.createReferral); router.get('/referrals/mine', authenticate, talentGraphController.listMyReferrals); diff --git a/gitgram/backend/src/services/talentGapAnalysisService.ts b/gitgram/backend/src/services/talentGapAnalysisService.ts new file mode 100644 index 00000000..3def8f16 --- /dev/null +++ b/gitgram/backend/src/services/talentGapAnalysisService.ts @@ -0,0 +1,157 @@ +/** + * Need-coverage / gap analysis. + * + * Answers ARCHITECTURE.md §3.1 competency question #7 — "Which needs are + * currently unmatched because no person covers skill set S?" — and delivers the + * L3 done-ladder "unmatched-need gap analysis" (ARCHITECTURE.md §5.5). + * + * Rung 2 canonicalized skills and taught `findTalentMatches` to score candidates + * per Need. This rung inverts that view: instead of "who matches this Need", it + * asks "which required skills does the current talent pool actually cover, and at + * what evidence strength". An org posting a Need needs to know its *gaps* — the + * skills for which no verifiable person exists — not just its top candidates. + * + * Design mirrors skillTaxonomyService: the core `analyzeNeedCoverage` is pure and + * dependency-free (no Prisma, no I/O) so it is unit-testable in isolation against + * plain match objects. `getNeedCoverage` is the thin orchestrator that runs the + * matcher and feeds it in; its `db` is injectable so it too tests without a live + * Postgres. Coverage strength ranks evidence exactly as the matcher does: + * verified > evidenced (any repo/pilot proof) > interest-only > unmet. + */ +import { canonicalizeSkills } from './skillTaxonomyService'; +import { findTalentMatches } from './talentGraphService'; +import prisma from '../utils/prisma'; + +type EvidenceLevel = 'verified' | 'linked' | 'recorded'; + +/** + * The strongest signal any candidate offers for a single required skill, ranked + * the way the matcher ranks evidence. + */ +export type CoverageStrength = 'verified' | 'evidenced' | 'interest' | 'unmet'; + +/** + * The minimal, structural shape of a match this analyzer reads. Compatible with + * (a superset of) the objects returned by `findTalentMatches`, but decoupled from + * its full inferred type so it can be unit-tested with hand-built fixtures. + */ +export interface CandidateCoverage { + readonly matchedSkills: readonly string[]; + readonly projects: readonly { + readonly matchedSkills: readonly string[]; + readonly verificationLevel: EvidenceLevel; + }[]; +} + +export interface SkillCoverage { + /** Canonical skill token. */ + skill: string; + /** Strongest evidence strength any candidate offers for this skill. */ + strength: CoverageStrength; + /** Candidates with any signal (repo/pilot evidence or interest) for the skill. */ + candidateCount: number; + /** Candidates whose repo/pilot evidence covers the skill. */ + evidencedCount: number; + /** Candidates whose *verified-tier* evidence covers the skill. */ + verifiedCount: number; +} + +export interface NeedCoverageAnalysis { + /** Canonicalized, de-duplicated required skills the analysis was run over. */ + requiredSkills: string[]; + /** Per-skill coverage, in the input skill order. */ + coverage: SkillCoverage[]; + /** Required skills no candidate covers with any signal — the gap. */ + unmetSkills: string[]; + /** Fraction of required skills covered by at least one candidate (0..1). */ + coverageRatio: number; + /** Roll-up status for the whole Need. */ + status: 'fully-covered' | 'partially-covered' | 'unmet'; + /** Size of the candidate pool the analysis considered. */ + candidatePool: number; +} + +type TalentCoverageDb = Parameters[2]; + +function classify(verifiedCount: number, evidencedCount: number, candidateCount: number): CoverageStrength { + if (verifiedCount > 0) return 'verified'; + if (evidencedCount > 0) return 'evidenced'; + if (candidateCount > 0) return 'interest'; + return 'unmet'; +} + +/** + * Pure gap analysis: given the raw required skills of a Need and the candidate + * matches for it, report which skills the pool covers and how strongly. No I/O. + * + * Skills are canonicalized first (reusing rung 2) so the report keys line up with + * the canonical tokens the matcher scores on — an org asking for "JavaScript" and + * a candidate whose repo language is "js" resolve to the same coverage row. + */ +export function analyzeNeedCoverage( + requiredSkills: readonly string[], + matches: readonly CandidateCoverage[], +): NeedCoverageAnalysis { + const skills = canonicalizeSkills([...requiredSkills]); + + const coverage: SkillCoverage[] = skills.map((skill) => { + let candidateCount = 0; + let evidencedCount = 0; + let verifiedCount = 0; + + for (const match of matches) { + const evidencedProjects = match.projects.filter((project) => project.matchedSkills.includes(skill)); + const hasEvidence = evidencedProjects.length > 0; + const hasVerified = evidencedProjects.some((project) => project.verificationLevel === 'verified'); + // `matchedSkills` already unions evidence + interest signals, so it is the + // "any signal" test; evidence/verified are the stronger nested tiers. + const hasAnySignal = match.matchedSkills.includes(skill) || hasEvidence; + + if (hasAnySignal) candidateCount += 1; + if (hasEvidence) evidencedCount += 1; + if (hasVerified) verifiedCount += 1; + } + + return { + skill, + strength: classify(verifiedCount, evidencedCount, candidateCount), + candidateCount, + evidencedCount, + verifiedCount, + }; + }); + + const unmetSkills = coverage.filter((entry) => entry.candidateCount === 0).map((entry) => entry.skill); + const coveredCount = skills.length - unmetSkills.length; + const coverageRatio = skills.length === 0 ? 0 : Math.round((coveredCount / skills.length) * 100) / 100; + const status: NeedCoverageAnalysis['status'] = + skills.length === 0 || unmetSkills.length === skills.length + ? 'unmet' + : unmetSkills.length === 0 + ? 'fully-covered' + : 'partially-covered'; + + return { + requiredSkills: skills, + coverage, + unmetSkills, + coverageRatio, + status, + candidatePool: matches.length, + }; +} + +/** + * Orchestrator: run the evidence matcher for a Need's required skills, then fold + * the results into a coverage/gap report. `db` is injectable (defaults to the + * shared Prisma client) so callers and tests can supply a fake, mirroring + * `findTalentMatches`. + */ +export async function getNeedCoverage( + requiredSkills: string[], + limit = 25, + db: TalentCoverageDb = prisma, +): Promise { + const matches = await findTalentMatches(requiredSkills, limit, db); + return analyzeNeedCoverage(requiredSkills, matches); +} diff --git a/gitgram/backend/tests/unit/talentGapAnalysis.test.ts b/gitgram/backend/tests/unit/talentGapAnalysis.test.ts new file mode 100644 index 00000000..8935fbb0 --- /dev/null +++ b/gitgram/backend/tests/unit/talentGapAnalysis.test.ts @@ -0,0 +1,155 @@ +/** + * Unit tests for talentGapAnalysisService (ARCHITECTURE.md §3.1 CQ#7, §5.5 L3). + * + * `analyzeNeedCoverage` is pure — no Prisma, no I/O — so it runs against + * hand-built match objects. `getNeedCoverage` takes the same injectable `db` + * (Pick) as the matcher, so the + * orchestration path also runs fully in-memory. These lock the gap-analysis + * contract an org relies on to see which required skills its talent pool covers, + * at what evidence strength, and which are unmet. + */ +import { + analyzeNeedCoverage, + getNeedCoverage, + type CandidateCoverage, +} from '../../src/services/talentGapAnalysisService'; + +function candidate( + matchedSkills: string[], + projects: Array<{ matchedSkills: string[]; verificationLevel: 'verified' | 'linked' | 'recorded' }> = [], +): CandidateCoverage { + return { matchedSkills, projects }; +} + +describe('analyzeNeedCoverage', () => { + it('canonicalizes required skills before reporting coverage', () => { + const analysis = analyzeNeedCoverage(['JavaScript', 'js'], []); + // "JavaScript" and "js" collapse to one canonical skill row. + expect(analysis.requiredSkills).toEqual(['javascript']); + expect(analysis.coverage).toHaveLength(1); + }); + + it('flags every required skill as unmet when the pool is empty', () => { + const analysis = analyzeNeedCoverage(['React', 'Go'], []); + expect(analysis.unmetSkills.sort()).toEqual(['golang', 'react']); + expect(analysis.coverageRatio).toBe(0); + expect(analysis.status).toBe('unmet'); + expect(analysis.candidatePool).toBe(0); + expect(analysis.coverage.every((entry) => entry.strength === 'unmet')).toBe(true); + }); + + it('reports verified strength when a candidate has verified evidence for a skill', () => { + const matches = [ + candidate(['typescript'], [{ matchedSkills: ['typescript'], verificationLevel: 'verified' }]), + ]; + const analysis = analyzeNeedCoverage(['TypeScript'], matches); + const [entry] = analysis.coverage; + expect(entry.strength).toBe('verified'); + expect(entry.verifiedCount).toBe(1); + expect(entry.evidencedCount).toBe(1); + expect(entry.candidateCount).toBe(1); + expect(analysis.unmetSkills).toEqual([]); + expect(analysis.status).toBe('fully-covered'); + expect(analysis.coverageRatio).toBe(1); + }); + + it('ranks recorded evidence below verified but above interest-only', () => { + const matches = [ + candidate(['react'], [{ matchedSkills: ['react'], verificationLevel: 'recorded' }]), + ]; + const [entry] = analyzeNeedCoverage(['React'], matches).coverage; + expect(entry.strength).toBe('evidenced'); + expect(entry.verifiedCount).toBe(0); + expect(entry.evidencedCount).toBe(1); + expect(entry.candidateCount).toBe(1); + }); + + it('reports interest-only strength when a skill has a signal but no project evidence', () => { + const matches = [candidate(['golang'], [])]; + const [entry] = analyzeNeedCoverage(['Go'], matches).coverage; + expect(entry.strength).toBe('interest'); + expect(entry.evidencedCount).toBe(0); + expect(entry.candidateCount).toBe(1); + }); + + it('produces a partially-covered status with the precise gap and ratio', () => { + const matches = [ + candidate(['typescript'], [{ matchedSkills: ['typescript'], verificationLevel: 'verified' }]), + ]; + const analysis = analyzeNeedCoverage(['TypeScript', 'kubernetes', 'python'], matches); + expect(analysis.unmetSkills.sort()).toEqual(['kubernetes', 'python']); + expect(analysis.status).toBe('partially-covered'); + // 1 of 3 covered → 0.33 + expect(analysis.coverageRatio).toBe(0.33); + expect(analysis.candidatePool).toBe(1); + }); + + it('counts distinct candidates and keeps the strongest strength per skill', () => { + const matches = [ + candidate(['react'], [{ matchedSkills: ['react'], verificationLevel: 'recorded' }]), + candidate(['react'], [{ matchedSkills: ['react'], verificationLevel: 'verified' }]), + candidate(['react'], []), // interest-only + ]; + const [entry] = analyzeNeedCoverage(['React'], matches).coverage; + expect(entry.candidateCount).toBe(3); + expect(entry.evidencedCount).toBe(2); + expect(entry.verifiedCount).toBe(1); + // strongest wins + expect(entry.strength).toBe('verified'); + }); +}); + +describe('getNeedCoverage', () => { + function makeDb(users: unknown[], proofs: unknown[] = []) { + return { + talentPublicProof: { findMany: async () => proofs }, + user: { findMany: async () => users }, + // eslint-disable-next-line @typescript-eslint/no-explicit-any + } as any; + } + + it('runs the matcher and folds results into a coverage report (verified via claimed repo)', async () => { + const user = { + id: 'u1', + username: 'ada', + displayName: null, + avatar: null, + avatarUrl: null, + bio: null, + githubUsername: null, + interests: [], + managedRepos: [ + { + role: 'OWNER', + repository: { + id: 'r1', + fullName: 'acme/r1', + htmlUrl: 'https://github.com/acme/r1', + language: 'js', + topics: [], + claimedBy: 'u1', + lastFetched: null, + lastSynced: null, + }, + }, + ], + }; + + const analysis = await getNeedCoverage(['JavaScript', 'python'], 25, makeDb([user])); + + expect(analysis.requiredSkills).toEqual(['javascript', 'python']); + expect(analysis.candidatePool).toBe(1); + const js = analysis.coverage.find((entry) => entry.skill === 'javascript'); + expect(js?.strength).toBe('verified'); + expect(analysis.unmetSkills).toEqual(['python']); + expect(analysis.status).toBe('partially-covered'); + expect(analysis.coverageRatio).toBe(0.5); + }); + + it('reports a fully-unmet Need when the matcher returns no candidates', async () => { + const analysis = await getNeedCoverage(['Rust'], 25, makeDb([])); + expect(analysis.status).toBe('unmet'); + expect(analysis.unmetSkills).toEqual(['rust']); + expect(analysis.candidatePool).toBe(0); + }); +});