feat: talent-graph module (dossier + match) on hardened schema

This commit is contained in:
caelum0x 2026-08-25 03:21:30 +03:00
parent 9cbad2bde3
commit d9d62a7fad
4 changed files with 417 additions and 12 deletions

View File

@ -0,0 +1,141 @@
/**
* Canonical skills taxonomy.
*
* Promotes the latent "Skill" entity (ARCHITECTURE.md §3.2, §5.4 #3) from a bare
* string attribute to a canonicalized token with a curated alias vocabulary.
* This is the entity-link step of the matcher (ARCHITECTURE.md §3.5, step 1):
* a Need's `requiredSkills`, a repo's `language`/`topics`, a user's `interests`,
* and a pilot's `evidenceSkills` are all free-text tokens sourced from GitHub or
* institutions. Without canonicalization an org that requires "JavaScript" never
* matches a repo tagged "js", so match recall silently collapses.
*
* Design:
* - `normalizeSkill` gives a stable comparison key (trim + lowercase + collapse
* internal whitespace). Backward compatible with the previous inline helper.
* - `canonicalizeSkill` maps a normalized token to its canonical form via the
* alias index, falling back to the normalized token when unknown.
* - `expandSkillAliases` / `expandSkillQueryTokens` widen a canonical skill back
* out to every known surface form so array-overlap DB filters (`hasSome`) catch
* aliased rows before they are re-canonicalized and scored.
*
* Pure and dependency-free: no Prisma, no I/O. Unit-testable in isolation.
*/
/**
* Curated canonical skill vocabulary. Keys are canonical tokens (already in
* normalized form); values are the additional aliases that resolve to them.
* Keep entries lowercase and normalized — they are indexed as-is.
*/
const SKILL_ALIASES: Readonly<Record<string, readonly string[]>> = {
javascript: ['js', 'node', 'nodejs', 'node.js', 'ecmascript', 'es6'],
typescript: ['ts'],
python: ['py', 'python3'],
react: ['reactjs', 'react.js'],
'react native': ['react-native', 'reactnative', 'rn'],
'next.js': ['next', 'nextjs'],
'node.js backend': ['express', 'expressjs'],
golang: ['go'],
'c#': ['csharp', 'c-sharp', 'dotnet', '.net'],
'c++': ['cpp', 'cplusplus'],
postgresql: ['postgres', 'psql', 'pg'],
kubernetes: ['k8s'],
'machine learning': ['ml', 'machine-learning'],
'artificial intelligence': ['ai'],
'devops': ['dev-ops', 'ci/cd', 'cicd'],
graphql: ['gql'],
tailwindcss: ['tailwind', 'tailwind css'],
postgres_prisma: ['prisma'],
};
/**
* Reverse index: every alias (and every canonical key) → canonical token.
* Built once at module load.
*/
const ALIAS_TO_CANONICAL: ReadonlyMap<string, string> = (() => {
const index = new Map<string, string>();
for (const [canonical, aliases] of Object.entries(SKILL_ALIASES)) {
index.set(canonical, canonical);
for (const alias of aliases) {
const key = normalizeSkill(alias);
// First writer wins so an accidental duplicate alias cannot silently
// repoint an existing canonical skill.
if (key && !index.has(key)) index.set(key, canonical);
}
}
return index;
})();
/**
* Forward index: canonical token → the full set of surface tokens (canonical +
* aliases) that should be queried for it.
*/
const CANONICAL_TO_TOKENS: ReadonlyMap<string, readonly string[]> = (() => {
const index = new Map<string, readonly string[]>();
for (const [canonical, aliases] of Object.entries(SKILL_ALIASES)) {
const tokens = new Set<string>([canonical]);
for (const alias of aliases) {
const key = normalizeSkill(alias);
if (key) tokens.add(key);
}
index.set(canonical, Array.from(tokens));
}
return index;
})();
/**
* Stable comparison key for a raw skill token: trimmed, lowercased, with
* internal whitespace collapsed to a single space.
*/
export function normalizeSkill(value: string): string {
return value.trim().toLowerCase().replace(/\s+/g, ' ');
}
/**
* Resolve a raw skill token to its canonical form. Unknown tokens fall back to
* their normalized value so the matcher still compares like-for-like.
*/
export function canonicalizeSkill(value: string): string {
const normalized = normalizeSkill(value);
if (!normalized) return '';
return ALIAS_TO_CANONICAL.get(normalized) ?? normalized;
}
/**
* Canonicalize a list of raw skill tokens, dropping empties and de-duplicating
* while preserving first-seen order.
*/
export function canonicalizeSkills(values: readonly string[]): string[] {
const seen = new Set<string>();
const result: string[] = [];
for (const value of values) {
const canonical = canonicalizeSkill(value);
if (canonical && !seen.has(canonical)) {
seen.add(canonical);
result.push(canonical);
}
}
return result;
}
/**
* Expand a canonical skill back to every known surface token (canonical +
* aliases). Unknown tokens expand to themselves.
*/
export function expandSkillAliases(canonical: string): string[] {
const key = normalizeSkill(canonical);
const tokens = CANONICAL_TO_TOKENS.get(key);
return tokens ? Array.from(tokens) : key ? [key] : [];
}
/**
* Build the de-duplicated union of surface tokens for a set of canonical skills.
* Use this for array-overlap DB filters (`hasSome` / `in`) so aliased rows are
* retrieved before being re-canonicalized and scored.
*/
export function expandSkillQueryTokens(canonicalSkills: readonly string[]): string[] {
const tokens = new Set<string>();
for (const skill of canonicalSkills) {
for (const token of expandSkillAliases(skill)) tokens.add(token);
}
return Array.from(tokens);
}

View File

@ -1,5 +1,6 @@
import prisma from '../utils/prisma';
import { normalizePublicHttpUrl } from '../utils/publicHttpUrl';
import { canonicalizeSkill, canonicalizeSkills, expandSkillQueryTokens } from './skillTaxonomyService';
import type { PrismaClient } from '@prisma/client';
type EvidenceLevel = 'verified' | 'linked' | 'recorded';
@ -51,10 +52,6 @@ interface CompletedPilotEvidence {
type TalentMatchDb = Pick<PrismaClient, 'talentPublicProof' | 'user'>;
function normalizeSkill(value: string) {
return value.trim().toLowerCase();
}
function projectKey(owner: string | null, name: string, fullName: string | null) {
return (fullName || (owner ? `${owner}/${name}` : name)).toLowerCase();
}
@ -383,13 +380,19 @@ export async function getTalentGraph(userId: string, options: { publicView?: boo
}
export async function findTalentMatches(requiredSkills: string[], limit = 12, db: TalentMatchDb = prisma) {
const skills = Array.from(new Set(requiredSkills.map(normalizeSkill).filter(Boolean))).slice(0, 12);
// Entity-link the Need: resolve required skills to canonical Skill tokens
// (ARCHITECTURE.md §3.5, step 1). Scoring compares canonical-to-canonical.
const skills = canonicalizeSkills(requiredSkills).slice(0, 12);
if (skills.length === 0) return [];
// Widen the retrieval filters to every known alias so array-overlap queries
// catch rows stored under a surface form (e.g. "js") before re-canonicalizing.
const queryTokens = expandSkillQueryTokens(skills);
const completedPilots = await db.talentPublicProof.findMany({
where: {
schemaVersion: 1,
evidenceSkills: { hasSome: skills },
evidenceSkills: { hasSome: queryTokens },
},
orderBy: { completedAt: 'desc' },
take: 200,
@ -409,7 +412,7 @@ export async function findTalentMatches(requiredSkills: string[], limit = 12, db
isSuspended: false,
username: { not: null },
OR: [
{ interests: { hasSome: skills } },
{ interests: { hasSome: queryTokens } },
...(pilotParticipantIds.length > 0 ? [{ id: { in: pilotParticipantIds } }] : []),
{
managedRepos: {
@ -417,8 +420,8 @@ export async function findTalentMatches(requiredSkills: string[], limit = 12, db
repository: {
isPrivate: false,
OR: [
{ topics: { hasSome: skills } },
{ language: { in: skills, mode: 'insensitive' } },
{ topics: { hasSome: queryTokens } },
{ language: { in: queryTokens, mode: 'insensitive' } },
],
},
},
@ -459,9 +462,9 @@ export async function findTalentMatches(requiredSkills: string[], limit = 12, db
return users
.map((user) => {
const interestMatches = user.interests.map(normalizeSkill).filter((skill) => skills.includes(skill));
const interestMatches = user.interests.map(canonicalizeSkill).filter((skill) => skills.includes(skill));
const repositoryProjects: TalentMatchProject[] = user.managedRepos.flatMap((manager) => {
const repositorySkills = [manager.repository.language || '', ...manager.repository.topics].map(normalizeSkill);
const repositorySkills = [manager.repository.language || '', ...manager.repository.topics].map(canonicalizeSkill);
const matchedSkills = skills.filter((skill) => repositorySkills.includes(skill));
if (matchedSkills.length === 0) return [];
return [{
@ -475,7 +478,7 @@ export async function findTalentMatches(requiredSkills: string[], limit = 12, db
const pilotProjects: TalentMatchProject[] = (pilotsByParticipant.get(user.id) || []).flatMap((pilot) => {
const deliverableUrl = normalizePublicHttpUrl(pilot.deliverableUrl);
if (!deliverableUrl) return [];
const matchedSkills = skills.filter((skill) => pilot.evidenceSkills.map(normalizeSkill).includes(skill));
const matchedSkills = skills.filter((skill) => pilot.evidenceSkills.map(canonicalizeSkill).includes(skill));
if (matchedSkills.length === 0) return [];
return [{
id: pilot.publicId,

View File

@ -0,0 +1,89 @@
/**
* Unit tests for skillTaxonomyService.
*
* Pure functions — no Prisma, no I/O. These lock the canonicalization contract
* the talent matcher relies on (ARCHITECTURE.md §3.5 step 1).
*/
import {
canonicalizeSkill,
canonicalizeSkills,
expandSkillAliases,
expandSkillQueryTokens,
normalizeSkill,
} from '../../src/services/skillTaxonomyService';
describe('skillTaxonomyService.normalizeSkill', () => {
it('trims, lowercases, and collapses internal whitespace', () => {
expect(normalizeSkill(' React Native ')).toBe('react native');
expect(normalizeSkill('TypeScript')).toBe('typescript');
expect(normalizeSkill('')).toBe('');
});
});
describe('skillTaxonomyService.canonicalizeSkill', () => {
it('resolves known aliases to their canonical token', () => {
expect(canonicalizeSkill('js')).toBe('javascript');
expect(canonicalizeSkill('Node.js')).toBe('javascript');
expect(canonicalizeSkill('TS')).toBe('typescript');
expect(canonicalizeSkill('reactjs')).toBe('react');
expect(canonicalizeSkill('k8s')).toBe('kubernetes');
expect(canonicalizeSkill('Go')).toBe('golang');
});
it('is idempotent on canonical tokens', () => {
expect(canonicalizeSkill('javascript')).toBe('javascript');
expect(canonicalizeSkill('react native')).toBe('react native');
});
it('falls back to the normalized token when unknown', () => {
expect(canonicalizeSkill(' Rust ')).toBe('rust');
expect(canonicalizeSkill('COBOL')).toBe('cobol');
});
it('returns an empty string for blank input', () => {
expect(canonicalizeSkill(' ')).toBe('');
});
});
describe('skillTaxonomyService.canonicalizeSkills', () => {
it('canonicalizes, de-duplicates by canonical form, and preserves order', () => {
expect(canonicalizeSkills(['JavaScript', 'js', 'node', 'React', 'reactjs'])).toEqual([
'javascript',
'react',
]);
});
it('drops blank tokens', () => {
expect(canonicalizeSkills([' ', 'ts', ''])).toEqual(['typescript']);
});
});
describe('skillTaxonomyService.expandSkillAliases', () => {
it('expands a canonical skill to every known surface token', () => {
const tokens = expandSkillAliases('javascript');
expect(tokens).toContain('javascript');
expect(tokens).toContain('js');
expect(tokens).toContain('node.js');
// no duplicates
expect(new Set(tokens).size).toBe(tokens.length);
});
it('expands an unknown token to itself', () => {
expect(expandSkillAliases('rust')).toEqual(['rust']);
});
it('returns an empty array for blank input', () => {
expect(expandSkillAliases(' ')).toEqual([]);
});
});
describe('skillTaxonomyService.expandSkillQueryTokens', () => {
it('unions the surface tokens of several canonical skills without duplicates', () => {
const tokens = expandSkillQueryTokens(['javascript', 'typescript']);
expect(tokens).toContain('js');
expect(tokens).toContain('javascript');
expect(tokens).toContain('ts');
expect(tokens).toContain('typescript');
expect(new Set(tokens).size).toBe(tokens.length);
});
});

View File

@ -0,0 +1,172 @@
/**
* Unit tests for findTalentMatches (the evidence matcher, ARCHITECTURE.md §1.3B).
*
* The service accepts an injectable `db` (Pick<PrismaClient, 'talentPublicProof'
* | 'user'>), so these run fully in-memory against a hand-built fake — no live
* Postgres. They assert the load-bearing behavior added in this rung: required
* skills and candidate evidence are canonicalized before scoring, so aliased
* tokens (e.g. Need "JavaScript" vs repo language "js") still match.
*/
import { findTalentMatches } from '../../src/services/talentGraphService';
type FakeUser = {
id: string;
username: string | null;
displayName: string | null;
avatar: string | null;
avatarUrl: string | null;
bio: string | null;
githubUsername: string | null;
interests: string[];
managedRepos: Array<{
role: string;
repository: {
id: string;
fullName: string;
htmlUrl: string;
language: string | null;
topics: string[];
claimedBy: string | null;
lastFetched: Date | null;
lastSynced: Date | null;
};
}>;
};
type FakeProof = {
publicId: string;
participantId: string;
deliverableUrl: string | null;
evidenceSkills: string[];
completedAt: Date;
};
function makeUser(overrides: Partial<FakeUser> & { id: string }): FakeUser {
return {
username: `user-${overrides.id}`,
displayName: null,
avatar: null,
avatarUrl: null,
bio: null,
githubUsername: null,
interests: [],
managedRepos: [],
...overrides,
};
}
function makeRepo(overrides: Partial<FakeUser['managedRepos'][number]['repository']> & { id: string }) {
return {
fullName: `acme/${overrides.id}`,
htmlUrl: `https://github.com/acme/${overrides.id}`,
language: null,
topics: [],
claimedBy: null,
lastFetched: null,
lastSynced: null,
...overrides,
};
}
function makeDb(users: FakeUser[], proofs: FakeProof[] = []) {
return {
talentPublicProof: { findMany: async () => proofs },
user: { findMany: async () => users },
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any;
}
describe('findTalentMatches', () => {
it('returns an empty array when no skills are requested', async () => {
const result = await findTalentMatches([' ', ''], 12, makeDb([]));
expect(result).toEqual([]);
});
it('matches a repo whose language is an alias of the required skill (verified)', async () => {
const user = makeUser({
id: 'u1',
username: 'ada',
managedRepos: [
{ role: 'OWNER', repository: makeRepo({ id: 'r1', language: 'js', claimedBy: 'u1' }) },
],
});
const [match] = await findTalentMatches(['JavaScript'], 12, makeDb([user]));
expect(match.profile.username).toBe('ada');
expect(match.matchedSkills).toEqual(['javascript']);
expect(match.missingSkills).toEqual([]);
expect(match.projects).toHaveLength(1);
expect(match.projects[0].verificationLevel).toBe('verified');
// coverage 1.0*75 + verified(1)*10 + projects(1)*5 = 90
expect(match.score).toBe(90);
expect(match.reason).toContain('depo kanıtıyla');
});
it('canonicalizes topics so aliased repo topics still count as evidence', async () => {
const user = makeUser({
id: 'u2',
username: 'grace',
managedRepos: [
{ role: 'MAINTAINER', repository: makeRepo({ id: 'r2', topics: ['reactjs', 'k8s'] }) },
],
});
const [match] = await findTalentMatches(['React', 'kubernetes'], 12, makeDb([user]));
expect(match.matchedSkills.sort()).toEqual(['kubernetes', 'react']);
expect(match.missingSkills).toEqual([]);
// recorded (not claimed) → verifiedProjects 0
expect(match.projects[0].verificationLevel).toBe('recorded');
});
it('treats interest-only overlap as the weakest signal', async () => {
const user = makeUser({
id: 'u3',
username: 'linus',
interests: ['Go'],
});
const [match] = await findTalentMatches(['golang'], 12, makeDb([user]));
expect(match.matchedSkills).toEqual(['golang']);
expect(match.projects).toEqual([]);
// coverage 1.0*75 only, no evidence projects
expect(match.score).toBe(75);
expect(match.reason).toContain('profil ilgi alanıyla');
});
it('ranks stronger evidence above interest-only matches', async () => {
const evidenced = makeUser({
id: 'strong',
username: 'strong',
managedRepos: [
{ role: 'OWNER', repository: makeRepo({ id: 'rs', language: 'typescript', claimedBy: 'strong' }) },
],
});
const interestOnly = makeUser({ id: 'weak', username: 'weak', interests: ['ts'] });
const results = await findTalentMatches(['TypeScript'], 12, makeDb([interestOnly, evidenced]));
expect(results.map((m) => m.profile.username)).toEqual(['strong', 'weak']);
expect(results[0].score).toBeGreaterThan(results[1].score);
});
it('surfaces completed pilot proof as verified evidence', async () => {
const user = makeUser({ id: 'p1', username: 'pilot-dev' });
const proof: FakeProof = {
publicId: 'proof-1',
participantId: 'p1',
deliverableUrl: 'https://example.com/deliverable',
evidenceSkills: ['python3'],
completedAt: new Date('2026-01-01'),
};
const [match] = await findTalentMatches(['Python'], 12, makeDb([user], [proof]));
expect(match.matchedSkills).toEqual(['python']);
expect(match.projects[0].verificationLevel).toBe('verified');
expect(match.projects[0].url).toBe('https://example.com/deliverable');
expect(match.reason).toContain('kurum pilotu');
});
});