feat: need-coverage / gap-analysis service + endpoint

This commit is contained in:
caelum0x 2026-08-25 03:42:36 +03:00
parent d9d62a7fad
commit a4e1464ce5
4 changed files with 323 additions and 0 deletions

View File

@ -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');

View File

@ -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);

View 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);
}

View 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);
});
});