Files
persona-lenz/apps/api/src/shared-contract.spec.ts
T
2026-07-03 00:29:51 -07:00

343 lines
9.3 KiB
TypeScript

import {
ADVANTAGE_EVENT_WEIGHTS,
FEATURE_SCHEMA_VERSION,
METRICS,
SUMMONERS_RIFT_MAP,
SUMMONERS_RIFT_MAP_ZONES,
VECTOR_DIMENSION,
type AnalysisRequestAcceptedDto,
type AnalysisJobStatusDto,
type AnalysisRequestDto,
type PlayerAnalysisDto,
} from '@persona-lenz/shared';
const MVP_1_METRIC_IDS = [
'kda',
'killParticipation',
'damageShare',
'damagePerMin',
'goldPerMin',
'csPerMin',
'visionScorePerMin',
'wardsKilledPerMin',
'controlWardsPlaced',
'deathsPerMin',
'objectiveParticipation',
'soloKills',
];
const MVP_2_TIMELINE_METRIC_IDS = [
'goldDiffAt10',
'goldDiffAt14',
'csDiffAt10',
'xpDiffAt10',
'deathsBefore14',
'killParticipationBefore14',
'earlyWardsPerMin',
'objectivePreWardRate',
'eliteObjectiveParticipationRate',
'isolationTendency',
'teamfightFirstEngagementParticipationRate',
'teamfightCleanupKillParticipationRate',
'deathWithShutdownBountyGivenRate',
'ccTimePerMinute',
];
const MVP_2_INSIGHT_METRIC_IDS = [
'objectiveFightOpeningParticipationRate',
'objectiveFightOpeningConvertedToObjectiveRate',
'preObjectivePitPresenceRate',
'preObjectivePickParticipationRate',
'deathFollowedByTeamLossRate',
'deathTradedForTeamAdvantageRate',
'deathWhileIsolatedFromNearestAllyRate',
'earlyDeficitRecoveryRate',
'laneLeadConversionRate',
'roamConvertedToTeamAdvantageRate',
'shutdownGoldCollectedPerGame',
'platePresenceParticipationRate',
'objectiveBountyComebackParticipationRate',
];
const MVP_2_METRIC_IDS = [
...MVP_1_METRIC_IDS,
...MVP_2_TIMELINE_METRIC_IDS,
...MVP_2_INSIGHT_METRIC_IDS,
];
const MVP_2_TIMELINE_METRIC_CONTRACTS = [
{ id: 'goldDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'goldDiffAt14', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'csDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'xpDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'deathsBefore14', kind: 'scalar', direction: 'lowerIsBetter' },
{
id: 'killParticipationBefore14',
kind: 'scalar',
direction: 'higherIsBetter',
},
{ id: 'earlyWardsPerMin', kind: 'scalar', direction: 'higherIsBetter' },
{ id: 'objectivePreWardRate', kind: 'ratio', direction: 'higherIsBetter' },
{
id: 'eliteObjectiveParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{ id: 'isolationTendency', kind: 'scalar', direction: 'lowerIsBetter' },
{
id: 'teamfightFirstEngagementParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'teamfightCleanupKillParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'deathWithShutdownBountyGivenRate',
kind: 'ratio',
direction: 'lowerIsBetter',
},
{ id: 'ccTimePerMinute', kind: 'scalar', direction: 'higherIsBetter' },
] as const;
const MVP_2_INSIGHT_METRIC_CONTRACTS = [
{
id: 'objectiveFightOpeningParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'objectiveFightOpeningConvertedToObjectiveRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'preObjectivePitPresenceRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'preObjectivePickParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'deathFollowedByTeamLossRate',
kind: 'ratio',
direction: 'lowerIsBetter',
},
{
id: 'deathTradedForTeamAdvantageRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'deathWhileIsolatedFromNearestAllyRate',
kind: 'ratio',
direction: 'lowerIsBetter',
},
{
id: 'earlyDeficitRecoveryRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'laneLeadConversionRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'roamConvertedToTeamAdvantageRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'shutdownGoldCollectedPerGame',
kind: 'scalar',
direction: 'higherIsBetter',
},
{
id: 'platePresenceParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
{
id: 'objectiveBountyComebackParticipationRate',
kind: 'ratio',
direction: 'higherIsBetter',
},
] as const;
describe('shared feature registry', () => {
it('defines MVP 2 vector metrics in the documented order', () => {
expect(FEATURE_SCHEMA_VERSION).toBe(2);
expect(METRICS.map((metric) => metric.id)).toEqual(MVP_2_METRIC_IDS);
expect(VECTOR_DIMENSION).toBe(26);
expect(
METRICS.filter((metric) => metric.includeInVector).map(
(metric) => metric.id,
),
).toEqual([...MVP_1_METRIC_IDS, ...MVP_2_TIMELINE_METRIC_IDS]);
expect(METRICS.filter((metric) => metric.includeInVector)).toHaveLength(
VECTOR_DIMENSION,
);
});
it('keeps metric ids unique and every metric normalizable by role', () => {
const metricIds = METRICS.map((metric) => metric.id);
expect(new Set(metricIds).size).toBe(metricIds.length);
for (const metric of METRICS) {
expect(metric.label).toBeTruthy();
expect(metric.baseline).toBeDefined();
expect(Object.keys(metric.baseline ?? {}).sort()).toEqual([
'BOTTOM',
'JUNGLE',
'MIDDLE',
'TOP',
'UTILITY',
]);
for (const range of Object.values(metric.baseline ?? {})) {
expect(range.min).toBeLessThan(range.max);
}
}
});
it('marks deaths per minute as lower-is-better for strength scoring', () => {
expect(
METRICS.find((metric) => metric.id === 'deathsPerMin')?.direction,
).toBe('lowerIsBetter');
expect(
METRICS.find((metric) => metric.id === 'deathWithShutdownBountyGivenRate')
?.direction,
).toBe('lowerIsBetter');
});
it('defines MVP 2 timeline metric aggregation contracts', () => {
expect(
MVP_2_TIMELINE_METRIC_IDS.map((metricId) => {
const metric = METRICS.find((candidate) => candidate.id === metricId);
return {
id: metric?.id,
kind: metric?.kind,
direction: metric?.direction,
includeInVector: metric?.includeInVector,
};
}),
).toEqual(
MVP_2_TIMELINE_METRIC_CONTRACTS.map((metric) => ({
...metric,
includeInVector: true,
})),
);
});
it('defines MVP 2 insight metric aggregation contracts outside the vector', () => {
expect(
MVP_2_INSIGHT_METRIC_IDS.map((metricId) => {
const metric = METRICS.find((candidate) => candidate.id === metricId);
return {
id: metric?.id,
kind: metric?.kind,
direction: metric?.direction,
includeInVector: metric?.includeInVector,
};
}),
).toEqual(
MVP_2_INSIGHT_METRIC_CONTRACTS.map((metric) => ({
...metric,
includeInVector: false,
})),
);
});
it('defines shared advantage event weights for timeline-derived metrics', () => {
expect(ADVANTAGE_EVENT_WEIGHTS).toEqual({
championKill: 1,
turretPlate: 0.5,
tower: 1.5,
dragon: 1.5,
riftHerald: 1.5,
baron: 3,
});
});
it('defines shared Summoner Rift map zones for timeline-derived metrics', () => {
expect(SUMMONERS_RIFT_MAP_ZONES).toEqual([
'blueBase',
'redBase',
'topLane',
'middleLane',
'bottomLane',
'river',
'northWestJungle',
'northEastJungle',
'southWestJungle',
'southEastJungle',
'dragonPit',
'baronPit',
'unknown',
]);
expect(SUMMONERS_RIFT_MAP).toEqual({
coordinateMin: 0,
coordinateMax: 15_000,
laneAxisHalfWidth: 1_500,
riverBandHalfWidth: 1_500,
jungleMidline: 7_500,
baseRadius: 2_200,
objectivePitRadius: 2_500,
dragonPit: { x: 9_866, y: 4_414 },
baronPit: { x: 5_007, y: 10_471 },
});
});
});
describe('shared DTO contracts', () => {
it('exports request, job status, and player analysis DTO shapes', () => {
const request: AnalysisRequestDto = {
gameName: 'Hide on bush',
tagLine: 'KR1',
platform: 'ph2',
matchCount: 20,
};
const jobStatus: AnalysisJobStatusDto = {
jobId: 'job-1',
status: 'processing',
stage: 'fetch-match-details',
puuid: 'puuid-1',
progress: { fetchedMatches: 3, totalMatches: 20 },
error: null,
};
const accepted: AnalysisRequestAcceptedDto = {
jobId: 'job-1',
status: 'queued',
};
const playstyle = Object.fromEntries(
MVP_2_METRIC_IDS.map((metricId) => [metricId, 0.5]),
) as PlayerAnalysisDto['profile']['playstyle'];
const analysis: PlayerAnalysisDto = {
account: {
gameName: 'Hide on bush',
tagLine: 'KR1',
profileIconId: 1,
tiers: [],
},
profile: {
mainRole: 'MIDDLE',
queueId: 420,
sampleGameCount: 12,
championPool: [{ championId: 103, games: 4, wins: 3 }],
playstyle,
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
confidence: 0.9,
},
strengths: [{ metricId: 'kda', value: 0.6 }],
weaknesses: [{ metricId: 'deathsPerMin', value: 0.7 }],
updatedAt: '2026-07-02T00:00:00.000Z',
};
expect(request.platform).toBe('ph2');
expect(accepted.status).toBe('queued');
expect(jobStatus.progress.totalMatches).toBe(20);
expect(analysis.profile.mainRole).toBe('MIDDLE');
});
});