From d9d62a7fadc09a22704f5af1b7fe996842285ec0 Mon Sep 17 00:00:00 2001 From: caelum0x Date: Tue, 25 Aug 2026 03:21:30 +0300 Subject: [PATCH] feat: talent-graph module (dossier + match) on hardened schema --- .../src/services/skillTaxonomyService.ts | 141 ++++++++++++++ .../src/services/talentGraphService.ts | 27 +-- .../tests/unit/skillTaxonomyService.test.ts | 89 +++++++++ .../tests/unit/talentGraphMatching.test.ts | 172 ++++++++++++++++++ 4 files changed, 417 insertions(+), 12 deletions(-) create mode 100644 gitgram/backend/src/services/skillTaxonomyService.ts create mode 100644 gitgram/backend/tests/unit/skillTaxonomyService.test.ts create mode 100644 gitgram/backend/tests/unit/talentGraphMatching.test.ts diff --git a/gitgram/backend/src/services/skillTaxonomyService.ts b/gitgram/backend/src/services/skillTaxonomyService.ts new file mode 100644 index 00000000..496973c5 --- /dev/null +++ b/gitgram/backend/src/services/skillTaxonomyService.ts @@ -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> = { + 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 = (() => { + const index = new Map(); + 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 = (() => { + const index = new Map(); + for (const [canonical, aliases] of Object.entries(SKILL_ALIASES)) { + const tokens = new Set([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(); + 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(); + for (const skill of canonicalSkills) { + for (const token of expandSkillAliases(skill)) tokens.add(token); + } + return Array.from(tokens); +} diff --git a/gitgram/backend/src/services/talentGraphService.ts b/gitgram/backend/src/services/talentGraphService.ts index 417bc999..d4d81b7f 100644 --- a/gitgram/backend/src/services/talentGraphService.ts +++ b/gitgram/backend/src/services/talentGraphService.ts @@ -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; -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, diff --git a/gitgram/backend/tests/unit/skillTaxonomyService.test.ts b/gitgram/backend/tests/unit/skillTaxonomyService.test.ts new file mode 100644 index 00000000..5acf7d25 --- /dev/null +++ b/gitgram/backend/tests/unit/skillTaxonomyService.test.ts @@ -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); + }); +}); diff --git a/gitgram/backend/tests/unit/talentGraphMatching.test.ts b/gitgram/backend/tests/unit/talentGraphMatching.test.ts new file mode 100644 index 00000000..313a7dc3 --- /dev/null +++ b/gitgram/backend/tests/unit/talentGraphMatching.test.ts @@ -0,0 +1,172 @@ +/** + * Unit tests for findTalentMatches (the evidence matcher, ARCHITECTURE.md §1.3B). + * + * The service accepts an injectable `db` (Pick), 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 & { 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 & { 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'); + }); +});