feat(graph): wire talent-graph validation gate into the service path (warn-only)
This commit is contained in:
parent
fd507e5efe
commit
b46c487206
@ -1,6 +1,9 @@
|
||||
import prisma from '../utils/prisma';
|
||||
import logger from '../utils/logger';
|
||||
import { normalizePublicHttpUrl } from '../utils/publicHttpUrl';
|
||||
import { canonicalizeSkill, canonicalizeSkills, expandSkillQueryTokens } from './skillTaxonomyService';
|
||||
import { deriveTalentEdges, type TalentGraphView } from './talentGraphEdges';
|
||||
import { validateEdges, type EdgeBatchResult } from './talentGraphOntology';
|
||||
import type { PrismaClient } from '@prisma/client';
|
||||
|
||||
type EvidenceLevel = 'verified' | 'linked' | 'recorded';
|
||||
@ -56,6 +59,38 @@ function projectKey(owner: string | null, name: string, fullName: string | null)
|
||||
return (fullName || (owner ? `${owner}/${name}` : name)).toLowerCase();
|
||||
}
|
||||
|
||||
/**
|
||||
* Non-breaking validation gate for the assembled talent graph.
|
||||
*
|
||||
* `getTalentGraph` assembles a read-only dossier; it does not persist edges. This
|
||||
* gate realizes the ontology guardrail on that read path: it derives typed,
|
||||
* provenanced candidate edges from the assembled view and vets them with
|
||||
* `validateEdges` (domain/range, provenance, symmetric dedup). It is WARN-ONLY —
|
||||
* it never mutates, drops, or reshapes the response. Ontology-invalid
|
||||
* ("hallucinated") structure is surfaced as a single structured warning (reason
|
||||
* codes + endpoint types) so violations are observable via logs/metrics without
|
||||
* changing any success-path output existing consumers depend on. Returns the
|
||||
* batch result so callers and tests can inspect what the gate saw.
|
||||
*/
|
||||
export function auditTalentGraphEdges(view: TalentGraphView): EdgeBatchResult {
|
||||
const result = validateEdges(deriveTalentEdges(view));
|
||||
if (result.rejected.length > 0) {
|
||||
logger.warn('talent-graph edge validation rejected ontology-invalid edges', {
|
||||
event: 'talent_graph.edge_validation.rejected',
|
||||
developerId: view.profile.id,
|
||||
acceptedCount: result.accepted.length,
|
||||
rejectedCount: result.rejected.length,
|
||||
rejections: result.rejected.map((entry) => ({
|
||||
edgeType: entry.input.type,
|
||||
fromType: entry.input.from?.type,
|
||||
toType: entry.input.to?.type,
|
||||
codes: entry.rejections.map((rejection) => rejection.code),
|
||||
})),
|
||||
});
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export async function getTalentGraph(userId: string, options: { publicView?: boolean } = {}) {
|
||||
const [user, syncedProjects, managedRepositories] = await Promise.all([
|
||||
prisma.user.findUnique({
|
||||
@ -356,7 +391,7 @@ export async function getTalentGraph(userId: string, options: { publicView?: boo
|
||||
(a, b) => b.sharedProjects.length - a.sharedProjects.length,
|
||||
);
|
||||
|
||||
return {
|
||||
const graph = {
|
||||
profile: {
|
||||
id: user.id,
|
||||
username: user.username,
|
||||
@ -377,6 +412,21 @@ export async function getTalentGraph(userId: string, options: { publicView?: boo
|
||||
collaborators: talentCollaborators,
|
||||
generatedAt: new Date(),
|
||||
};
|
||||
|
||||
// Realize the ontology guardrail on the read path. Warn-only and defensive:
|
||||
// the gate observes ontology-invalid structure but never changes `graph`, and a
|
||||
// failure here must never break a dossier read.
|
||||
try {
|
||||
auditTalentGraphEdges(graph);
|
||||
} catch (error) {
|
||||
logger.error('talent-graph edge validation gate failed', {
|
||||
event: 'talent_graph.edge_validation.error',
|
||||
developerId: user.id,
|
||||
error: error instanceof Error ? error.message : String(error),
|
||||
});
|
||||
}
|
||||
|
||||
return graph;
|
||||
}
|
||||
|
||||
export async function findTalentMatches(requiredSkills: string[], limit = 12, db: TalentMatchDb = prisma) {
|
||||
|
||||
171
gitgram/backend/tests/unit/talentGraphGate.test.ts
Normal file
171
gitgram/backend/tests/unit/talentGraphGate.test.ts
Normal file
@ -0,0 +1,171 @@
|
||||
/**
|
||||
* Tests for the talent-graph validation GATE (not just the ontology library).
|
||||
*
|
||||
* The ontology unit tests (talentGraphOntology.test.ts) prove validateEdge /
|
||||
* validateEdges are correct in isolation. These tests prove that the gate is
|
||||
* actually WIRED into the service read path — `getTalentGraph` runs the assembled
|
||||
* graph through `auditTalentGraphEdges` — and that it is non-breaking:
|
||||
* - valid edges pass through with no warning and the response shape is unchanged,
|
||||
* - an ontology-invalid edge (here: unparseable provenance timestamp from a
|
||||
* corrupt DB row) triggers exactly one structured warning while the dossier is
|
||||
* still returned intact (warn-only, nothing dropped, nothing reshaped).
|
||||
*
|
||||
* Prisma and the logger are mocked globally by tests/setup.ts.
|
||||
*/
|
||||
import { auditTalentGraphEdges, getTalentGraph } from '../../src/services/talentGraphService';
|
||||
import type { TalentGraphView } from '../../src/services/talentGraphEdges';
|
||||
import { mockPrisma } from '../setup';
|
||||
import logger from '../../src/utils/logger';
|
||||
|
||||
const warn = logger.warn as jest.Mock;
|
||||
|
||||
function makeView(overrides: Partial<TalentGraphView> = {}): TalentGraphView {
|
||||
return {
|
||||
profile: { id: 'dev-1' },
|
||||
projects: [
|
||||
{
|
||||
id: 'repo-1',
|
||||
url: 'https://github.com/acme/repo-1',
|
||||
topics: ['typescript'],
|
||||
verificationLevel: 'verified',
|
||||
lastVerifiedAt: new Date('2026-01-01T00:00:00Z'),
|
||||
evidence: [{ kind: 'repository_claim', sourceUrl: 'https://github.com/acme/repo-1' }],
|
||||
},
|
||||
],
|
||||
collaborators: [],
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('auditTalentGraphEdges (the gate)', () => {
|
||||
it('accepts well-typed edges from a clean view and emits no warning', () => {
|
||||
const result = auditTalentGraphEdges(makeView());
|
||||
|
||||
expect(result.rejected).toHaveLength(0);
|
||||
// developer→repo contribution + developer→skill has_skill.
|
||||
expect(result.accepted.length).toBeGreaterThanOrEqual(2);
|
||||
expect(warn).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('rejects an ontology-invalid edge and emits one structured warning (warn-only)', () => {
|
||||
// A corrupt DB timestamp flows into edge provenance as an unparseable date.
|
||||
const corrupt = makeView({
|
||||
projects: [
|
||||
{
|
||||
id: 'repo-1',
|
||||
url: 'https://github.com/acme/repo-1',
|
||||
topics: [],
|
||||
verificationLevel: 'verified',
|
||||
lastVerifiedAt: new Date('not-a-real-date'),
|
||||
evidence: [{ kind: 'repository_claim', sourceUrl: null }],
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
const result = auditTalentGraphEdges(corrupt);
|
||||
|
||||
expect(result.rejected.length).toBeGreaterThan(0);
|
||||
expect(result.rejected[0].rejections.map((r) => r.code)).toContain('invalid_observed_at');
|
||||
|
||||
expect(warn).toHaveBeenCalledTimes(1);
|
||||
const [message, meta] = warn.mock.calls[0];
|
||||
expect(message).toMatch(/edge validation rejected/i);
|
||||
expect(meta).toMatchObject({
|
||||
event: 'talent_graph.edge_validation.rejected',
|
||||
developerId: 'dev-1',
|
||||
rejectedCount: result.rejected.length,
|
||||
});
|
||||
expect(meta.rejections[0].codes).toContain('invalid_observed_at');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getTalentGraph invokes the gate on the real read path', () => {
|
||||
const userId = 'dev-real-1';
|
||||
|
||||
function seedUser() {
|
||||
mockPrisma.user.__rows = [
|
||||
{
|
||||
id: userId,
|
||||
username: 'dev-real',
|
||||
displayName: 'Dev Real',
|
||||
avatar: null,
|
||||
avatarUrl: null,
|
||||
bio: null,
|
||||
githubId: null,
|
||||
githubUsername: null,
|
||||
createdAt: new Date('2025-01-01T00:00:00Z'),
|
||||
isPrivate: false,
|
||||
},
|
||||
];
|
||||
// Unused-but-queried tables must resolve to empty sets.
|
||||
mockPrisma.repositoryManager.__rows = [];
|
||||
mockPrisma.repositoryActivity.__rows = [];
|
||||
// The talent* models are not part of the shared prisma mock; stub the reads
|
||||
// getTalentGraph performs so the assembly runs without touching a real DB.
|
||||
mockPrisma.talentPilot = { findMany: jest.fn().mockResolvedValue([]) };
|
||||
mockPrisma.talentPublicProof = { findMany: jest.fn().mockResolvedValue([]) };
|
||||
}
|
||||
|
||||
function seedProject(updatedAt: Date) {
|
||||
mockPrisma.project.__rows = [
|
||||
{
|
||||
id: 'proj-1',
|
||||
userId,
|
||||
owner: 'acme',
|
||||
name: 'repo-1',
|
||||
fullName: 'acme/repo-1',
|
||||
description: 'a project',
|
||||
url: 'https://github.com/acme/repo-1',
|
||||
repoUrl: 'https://github.com/acme/repo-1',
|
||||
language: 'TypeScript',
|
||||
tags: ['typescript'],
|
||||
stars: 3,
|
||||
forks: 1,
|
||||
githubId: null,
|
||||
updatedAt,
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
it('runs the gate and returns the unchanged dossier shape for clean data (no warning)', async () => {
|
||||
seedUser();
|
||||
seedProject(new Date('2026-02-01T00:00:00Z'));
|
||||
|
||||
const graph = await getTalentGraph(userId);
|
||||
|
||||
// Success-path response shape is exactly what consumers depend on.
|
||||
expect(graph).not.toBeNull();
|
||||
expect(graph).toEqual(
|
||||
expect.objectContaining({
|
||||
profile: expect.objectContaining({ id: userId }),
|
||||
summary: expect.objectContaining({ projectCount: 1 }),
|
||||
projects: expect.any(Array),
|
||||
collaborators: expect.any(Array),
|
||||
generatedAt: expect.any(Date),
|
||||
}),
|
||||
);
|
||||
expect(graph!.projects).toHaveLength(1);
|
||||
// Clean data => the gate found nothing to warn about.
|
||||
expect(warn).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('emits a gate warning when the assembled graph carries an ontology-invalid edge, still returning the dossier', async () => {
|
||||
seedUser();
|
||||
// Corrupt persisted timestamp -> invalid edge provenance on the read path.
|
||||
seedProject(new Date('totally-invalid'));
|
||||
|
||||
const graph = await getTalentGraph(userId);
|
||||
|
||||
// Warn-only: the dossier is still returned intact, nothing dropped.
|
||||
expect(graph).not.toBeNull();
|
||||
expect(graph!.projects).toHaveLength(1);
|
||||
|
||||
// The gate actually ran inside getTalentGraph and flagged the violation.
|
||||
expect(warn).toHaveBeenCalledTimes(1);
|
||||
const [, meta] = warn.mock.calls[0];
|
||||
expect(meta).toMatchObject({
|
||||
event: 'talent_graph.edge_validation.rejected',
|
||||
developerId: userId,
|
||||
});
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user