feat: need-coverage / gap-analysis service + endpoint
This commit is contained in:
parent
d9d62a7fad
commit
a4e1464ce5
@ -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');
|
||||
|
||||
@ -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);
|
||||
|
||||
157
gitgram/backend/src/services/talentGapAnalysisService.ts
Normal file
157
gitgram/backend/src/services/talentGapAnalysisService.ts
Normal file
@ -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<typeof findTalentMatches>[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<NeedCoverageAnalysis> {
|
||||
const matches = await findTalentMatches(requiredSkills, limit, db);
|
||||
return analyzeNeedCoverage(requiredSkills, matches);
|
||||
}
|
||||
155
gitgram/backend/tests/unit/talentGapAnalysis.test.ts
Normal file
155
gitgram/backend/tests/unit/talentGapAnalysis.test.ts
Normal file
@ -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<PrismaClient, 'talentPublicProof' | 'user'>) 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);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user