@cs2dak/core 0.2.0

package/src/signals.ts

@@ -0,0 +1,232 @@
+import {
+  computeLeagueMeanV2,
+  computeValueAccountsRR,
+  rrValueAccountsV2Lite
+} from "@rivalhub/rival-rating";
+import type { AccountSignalsV2, DemoPackage, ValueAccountsWeights } from "@cs2dak/contract";
+import type { RRResultV2 } from "@rivalhub/rival-rating";
+import { normalizeDemoPackage } from "./normalize.js";
+import {
+  type BuyDeltaBuckets,
+  type ManStateBuckets,
+  type ObjectiveBuckets,
+  type UtilityBuckets,
+  BUY_DELTA_EVEN_THRESHOLD,
+  getOrInit,
+  zeroBuyDelta,
+  zeroManState,
+  clutchSplitV2,
+  sumDamageForPlayer,
+  openingKillsForPlayer,
+  openingDeathsForPlayer,
+  multiKillRounds,
+  round,
+  firstKillMap
+} from "./utils.js";
+
+export function deriveAccountSignalsV2(input: unknown): AccountSignalsV2[] {
+  const pkg = normalizeDemoPackage(input);
+  const statsBySteamId = new Map(pkg.playerStats.map((row) => [row.steamId64, row]));
+  const killsByBuyDelta = buildKillsByBuyDelta(pkg);
+  const killsByManState = buildKillsByManState(pkg);
+  const tradedOpeningDeaths = buildTradedOpeningDeaths(pkg);
+  const objective = buildObjectiveSignals(pkg);
+  const utility = buildUtilitySignals(pkg);
+
+  // context 分桶的"数据源是否存在"。源缺失 → 发 null（模型降级为乘子 1.0），
+  // 而非零桶——零桶语义是"源在、但该选手无相关样本"。区分二者是 v2 可信展示的前提。
+  const buyDeltaAvailable = pkg.playerEconomies.length > 0;
+  const manStateAvailable = pkg.rounds.length > 0;
+
+  return pkg.players.map((player) => {
+    const stats = statsBySteamId.get(player.steamId64);
+    const playerKills = pkg.kills.filter((kill) => kill.killerSteamId64 === player.steamId64);
+    const playerDeaths = pkg.kills.filter((kill) => kill.victimSteamId64 === player.steamId64);
+    const playerClutches = pkg.clutches.filter((row) => row.clutcherSteamId64 === player.steamId64);
+    const rounds = Math.max(stats?.rounds ?? pkg.rounds.length, 0);
+
+    return {
+      steamId64: player.steamId64,
+      rounds,
+      sourceVersion: "cs2-demo-analysis-kit/0.3",
+      combat: {
+        kills: stats?.kills ?? playerKills.length,
+        deaths: stats?.deaths ?? playerDeaths.length,
+        assists: stats?.assists ?? 0,
+        effectiveDamage: stats?.damageHealth ?? sumDamageForPlayer(pkg, player.steamId64),
+        openingKills: stats?.firstKillCount ?? openingKillsForPlayer(pkg, player.steamId64),
+        openingDeaths: stats?.firstDeathCount ?? openingDeathsForPlayer(pkg, player.steamId64),
+        multiKills: {
+          two: stats?.twoKillCount ?? multiKillRounds(playerKills, 2),
+          three: stats?.threeKillCount ?? multiKillRounds(playerKills, 3),
+          four: stats?.fourKillCount ?? multiKillRounds(playerKills, 4),
+          five: stats?.fiveKillCount ?? multiKillRounds(playerKills, 5)
+        },
+        headshotKills: stats?.headshotCount ?? playerKills.filter((kill) => kill.headshot).length,
+        wallbangKills: stats?.wallbangKillCount ?? playerKills.filter((kill) => kill.penetratedObjects > 0).length,
+        killsByBuyDelta: buyDeltaAvailable ? (killsByBuyDelta.get(player.steamId64) ?? zeroBuyDelta()) : null,
+        killsByManState: manStateAvailable ? (killsByManState.get(player.steamId64) ?? zeroManState()) : null
+      },
+      trade: {
+        tradeKills: stats?.tradeKillCount ?? playerKills.filter((kill) => kill.tradeKill).length,
+        tradedDeaths: stats?.tradeDeathCount ?? playerDeaths.filter((kill) => kill.tradeDeath).length,
+        deaths: stats?.deaths ?? playerDeaths.length,
+        tradedOpeningDeaths: tradedOpeningDeaths.get(player.steamId64) ?? 0
+      },
+      clutch: {
+        vsOne: clutchSplitV2(stats?.vsOneCount, stats?.vsOneWonCount, playerClutches, 1),
+        vsTwo: clutchSplitV2(stats?.vsTwoCount, stats?.vsTwoWonCount, playerClutches, 2),
+        vsThree: clutchSplitV2(stats?.vsThreeCount, stats?.vsThreeWonCount, playerClutches, 3),
+        vsFour: clutchSplitV2(stats?.vsFourCount, stats?.vsFourWonCount, playerClutches, 4),
+        vsFive: clutchSplitV2(stats?.vsFiveCount, stats?.vsFiveWonCount, playerClutches, 5)
+      },
+      objective: objective.get(player.steamId64) ?? { plants: 0, defuses: 0, plantsConverted: 0 },
+      utility: utility.get(player.steamId64) ?? {
+        flashAssists: stats?.flashAssistCount ?? 0,
+        enemyFlashDurationSeconds: stats?.enemyFlashDurationSeconds ?? 0,
+        teamFlashDurationSeconds: stats?.teamFlashDurationSeconds ?? 0,
+        utilityDamage: stats?.utilityDamage ?? 0
+      }
+    } satisfies AccountSignalsV2;
+  });
+}
+
+export function computeAccountRatingsV2(input: unknown): Array<{ signals: AccountSignalsV2; rr: RRResultV2 }> {
+  const weights = rrValueAccountsV2Lite as unknown as ValueAccountsWeights;
+  const rated = deriveAccountSignalsV2(input).map((signals) => ({
+    signals,
+    rr: computeValueAccountsRR(signals, weights)
+  }));
+
+  // 联赛锚定（weights.anchor.mode === "league_mean"）：整体乘 (1.0 / mean)，
+  // 使 1.00 = 本场均值。本层一次只处理单场，故"联赛均值"= 本场均值（per-match）；
+  // 真正的赛季级锚定属于上游跨场聚合层，详见 docs/design/rr-v2-lite.md。
+  const mean = computeLeagueMeanV2(rated.map((row) => row.rr));
+  const factor = mean > 0 ? 1.0 / mean : 1.0;
+  return rated.map((row) => ({
+    signals: row.signals,
+    rr: { ...row.rr, rr: row.rr.rr * factor }
+  }));
+}
+
+function buildKillsByBuyDelta(pkg: DemoPackage): Map<string, BuyDeltaBuckets> {
+  const out = new Map<string, BuyDeltaBuckets>();
+  const economyByPlayerRound = new Map(pkg.playerEconomies.map((row) => [`${row.roundNumber}:${row.steamId64}`, row]));
+
+  for (const kill of pkg.kills) {
+    if (!kill.killerSteamId64) continue;
+    const killerEconomy = economyByPlayerRound.get(`${kill.roundNumber}:${kill.killerSteamId64}`);
+    const victimEconomy = economyByPlayerRound.get(`${kill.roundNumber}:${kill.victimSteamId64}`);
+    if (!killerEconomy || !victimEconomy) continue;
+
+    const buckets = getOrInit(out, kill.killerSteamId64, zeroBuyDelta);
+    const delta = killerEconomy.equipmentValue - victimEconomy.equipmentValue;
+    if (delta <= -BUY_DELTA_EVEN_THRESHOLD) {
+      buckets.disadvantage += 1;
+    } else if (delta >= BUY_DELTA_EVEN_THRESHOLD) {
+      buckets.advantage += 1;
+    } else {
+      buckets.even += 1;
+    }
+  }
+
+  return out;
+}
+
+function buildKillsByManState(pkg: DemoPackage): Map<string, ManStateBuckets> {
+  const out = new Map<string, ManStateBuckets>();
+  const playersByTeam = {
+    teamA: pkg.players.filter((player) => player.teamKey === "teamA").map((player) => player.steamId64),
+    teamB: pkg.players.filter((player) => player.teamKey === "teamB").map((player) => player.steamId64)
+  };
+
+  for (const roundRow of pkg.rounds) {
+    const alive = {
+      teamA: new Set(playersByTeam.teamA),
+      teamB: new Set(playersByTeam.teamB)
+    };
+    const roundKills = pkg.kills
+      .filter((kill) => kill.roundNumber === roundRow.roundNumber)
+      .sort((a, b) => a.tick - b.tick);
+
+    for (const kill of roundKills) {
+      if (kill.killerSteamId64 && kill.killerTeamKey && kill.killerTeamKey !== kill.victimTeamKey) {
+        const buckets = getOrInit(out, kill.killerSteamId64, zeroManState);
+        const killerAlive = alive[kill.killerTeamKey].size;
+        const victimAlive = alive[kill.victimTeamKey].size;
+        const diff = killerAlive - victimAlive;
+        if (diff < 0) {
+          buckets.manDown += 1;
+        } else if (diff > 0) {
+          buckets.manUp += 1;
+        } else {
+          buckets.even += 1;
+        }
+      }
+      alive[kill.victimTeamKey].delete(kill.victimSteamId64);
+    }
+  }
+
+  return out;
+}
+
+function buildTradedOpeningDeaths(pkg: DemoPackage): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const kill of firstKillMap(pkg).values()) {
+    if (kill.tradeDeath) {
+      out.set(kill.victimSteamId64, (out.get(kill.victimSteamId64) ?? 0) + 1);
+    }
+  }
+  return out;
+}
+
+function buildObjectiveSignals(pkg: DemoPackage): Map<string, ObjectiveBuckets> {
+  const out = new Map<string, ObjectiveBuckets>();
+  const roundWinner = new Map(pkg.rounds.map((round) => [round.roundNumber, round.winnerTeamKey]));
+
+  for (const bomb of pkg.bombs) {
+    if (!bomb.actorSteamId64) continue;
+    const buckets = getOrInit(out, bomb.actorSteamId64, () => ({ plants: 0, defuses: 0, plantsConverted: 0 }));
+    if (bomb.type === "planted") {
+      buckets.plants += 1;
+      if (bomb.actorTeamKey && roundWinner.get(bomb.roundNumber) === bomb.actorTeamKey) {
+        buckets.plantsConverted = (buckets.plantsConverted ?? 0) + 1;
+      }
+    } else if (bomb.type === "defused") {
+      buckets.defuses += 1;
+    }
+  }
+
+  return out;
+}
+
+function buildUtilitySignals(pkg: DemoPackage): Map<string, UtilityBuckets> {
+  const out = new Map<string, UtilityBuckets>();
+  const statsBySteamId = new Map(pkg.playerStats.map((row) => [row.steamId64, row]));
+
+  for (const player of pkg.players) {
+    const stats = statsBySteamId.get(player.steamId64);
+    out.set(player.steamId64, {
+      flashAssists: stats?.flashAssistCount ?? pkg.kills.filter((kill) => kill.flashAssisterSteamId64 === player.steamId64).length,
+      enemyFlashDurationSeconds: stats?.enemyFlashDurationSeconds ?? 0,
+      teamFlashDurationSeconds: stats?.teamFlashDurationSeconds ?? 0,
+      utilityDamage: stats?.utilityDamage ?? 0
+    });
+  }
+
+  for (const blind of pkg.blinds) {
+    const buckets = getOrInit(out, blind.flasherSteamId64, () => ({
+      flashAssists: 0,
+      enemyFlashDurationSeconds: 0,
+      teamFlashDurationSeconds: 0,
+      utilityDamage: 0
+    }));
+    if (blind.flasherTeamKey !== blind.flashedTeamKey) {
+      buckets.enemyFlashDurationSeconds = round(buckets.enemyFlashDurationSeconds + blind.durationSeconds, 3);
+    } else if (blind.flashedSteamId64 !== blind.flasherSteamId64) {
+      buckets.teamFlashDurationSeconds = round((buckets.teamFlashDurationSeconds ?? 0) + blind.durationSeconds, 3);
+    }
+  }
+
+  return out;
+}

package/src/timeline.ts

@@ -0,0 +1,209 @@
+import type { DemoPackage, EconomyPoint, HeatmapPoint, TimelineEvent } from "@cs2dak/contract";
+import { round, clamp, formatClock, nameForSteamId, normalizeWeapon } from "./utils.js";
+
+export function buildTimeline(pkg: DemoPackage): TimelineEvent[] {
+  const killEvents = pkg.kills.map<TimelineEvent>((kill, index) => ({
+    id: `kill-${index}`,
+    roundNumber: kill.roundNumber,
+    tick: kill.tick,
+    timeSeconds: tickToRoundSeconds(pkg, kill.roundNumber, kill.tick),
+    ...clockForTick(pkg, kill.roundNumber, kill.tick),
+    type: "kill",
+    label: `${nameForSteamId(pkg, kill.killerSteamId64) ?? "环境"} 击杀 ${nameForSteamId(pkg, kill.victimSteamId64)}`,
+    teamKey: kill.killerTeamKey
+  }));
+
+  const bombEvents = pkg.bombs.map<TimelineEvent>((bomb, index) => ({
+    id: `bomb-${index}`,
+    roundNumber: bomb.roundNumber,
+    tick: bomb.tick,
+    timeSeconds: tickToRoundSeconds(pkg, bomb.roundNumber, bomb.tick),
+    ...clockForTick(pkg, bomb.roundNumber, bomb.tick),
+    type: "bomb",
+    label: bombLabel(pkg, bomb),
+    teamKey: bomb.actorTeamKey
+  }));
+
+  const grenadeEvents = pkg.grenades.map<TimelineEvent>((grenade, index) => ({
+    id: `grenade-${index}`,
+    roundNumber: grenade.roundNumber,
+    tick: grenade.effectTick,
+    timeSeconds: tickToRoundSeconds(pkg, grenade.roundNumber, grenade.effectTick),
+    ...clockForTick(pkg, grenade.roundNumber, grenade.effectTick),
+    type: "grenade",
+    label: `${nameForSteamId(pkg, grenade.throwerSteamId64) ?? "未知选手"} 投掷${grenadeLabel(grenade.grenade)}`,
+    teamKey: grenade.throwerTeamKey
+  }));
+
+  const roundEvents = pkg.rounds.map<TimelineEvent>((roundRow) => ({
+    id: `round-end-${roundRow.roundNumber}`,
+    roundNumber: roundRow.roundNumber,
+    tick: roundRow.endTick,
+    timeSeconds: tickToRoundSeconds(pkg, roundRow.roundNumber, roundRow.endTick),
+    clockPhase: "round-end",
+    clockSeconds: 0,
+    clockLabel: "结束",
+    type: "round-end",
+    label: `${sideLabel(roundRow.winnerSide)}获胜 · ${endReasonLabel(roundRow.endReason)}`,
+    teamKey: roundRow.winnerTeamKey
+  }));
+
+  return [...killEvents, ...bombEvents, ...grenadeEvents, ...roundEvents]
+    .sort((a, b) => a.roundNumber - b.roundNumber || a.tick - b.tick || eventSortWeight(a.type) - eventSortWeight(b.type));
+}
+
+export function buildEconomy(pkg: DemoPackage): EconomyPoint[] {
+  return pkg.rounds.map((roundRow) => {
+    const rows = pkg.playerEconomies.filter((row) => row.roundNumber === roundRow.roundNumber);
+    const sumForTeam = (teamKey: "teamA" | "teamB") =>
+      rows
+        .filter((row) => row.teamKey === teamKey)
+        .reduce((sum, row) => sum + row.equipmentValue, 0);
+    const teamA = sumForTeam("teamA");
+    const teamB = sumForTeam("teamB");
+
+    return {
+      roundNumber: roundRow.roundNumber,
+      teamA,
+      teamB,
+      advantage: teamA - teamB,
+      teamAEconomy: roundRow.teamAEconomy,
+      teamBEconomy: roundRow.teamBEconomy,
+      winnerTeamKey: roundRow.winnerTeamKey
+    };
+  });
+}
+
+export function buildHeatmap(pkg: DemoPackage): HeatmapPoint[] {
+  // Pre-index sides per round to derive CT/T for any teamKey lookup.
+  const roundSides = new Map(
+    pkg.rounds.map((r) => [r.roundNumber, { teamA: r.teamASide, teamB: r.teamBSide }])
+  );
+  const sideFor = (teamKey: string | null, roundNumber: number): "ct" | "t" | null => {
+    if (!teamKey) return null;
+    const s = roundSides.get(roundNumber);
+    if (!s) return null;
+    return teamKey === "teamA" ? s.teamA : s.teamB;
+  };
+
+  const kills = pkg.kills.flatMap<HeatmapPoint>((kill) => {
+    const out: HeatmapPoint[] = [
+      {
+        x: kill.victimPosition.x,
+        y: kill.victimPosition.y,
+        z: kill.victimPosition.z,
+        roundNumber: kill.roundNumber,
+        teamKey: kill.victimTeamKey,
+        steamId64: kill.victimSteamId64,
+        side: sideFor(kill.victimTeamKey, kill.roundNumber),
+        kind: "death",
+        grenadeType: null
+      }
+    ];
+    if (kill.killerPosition) {
+      out.push({
+        x: kill.killerPosition.x,
+        y: kill.killerPosition.y,
+        z: kill.killerPosition.z,
+        roundNumber: kill.roundNumber,
+        teamKey: kill.killerTeamKey,
+        steamId64: kill.killerSteamId64,
+        side: sideFor(kill.killerTeamKey, kill.roundNumber),
+        kind: "kill",
+        grenadeType: null
+      });
+    }
+    return out;
+  });
+
+  const grenades = pkg.grenades
+    .map<HeatmapPoint>((grenade) => ({
+      x: grenade.effectPosition.x,
+      y: grenade.effectPosition.y,
+      z: grenade.effectPosition.z,
+      roundNumber: grenade.roundNumber,
+      teamKey: grenade.throwerTeamKey,
+      steamId64: grenade.throwerSteamId64,
+      side: sideFor(grenade.throwerTeamKey, grenade.roundNumber),
+      kind: "grenade",
+      grenadeType: grenade.grenade
+    }));
+
+  return [...kills, ...grenades].filter((point) => point.x !== 0 || point.y !== 0);
+}
+
+function tickToRoundSeconds(pkg: DemoPackage, roundNumber: number, tick: number): number {
+  const roundRow = pkg.rounds.find((row) => row.roundNumber === roundNumber);
+  if (!roundRow) {
+    return 0;
+  }
+  return round(Math.max(0, tick - roundRow.freezeEndTick) / pkg.match.tickrate, 2);
+}
+
+function clockForTick(pkg: DemoPackage, roundNumber: number, tick: number): Pick<TimelineEvent, "clockPhase" | "clockSeconds" | "clockLabel"> {
+  const roundRow = pkg.rounds.find((row) => row.roundNumber === roundNumber);
+  if (!roundRow) {
+    return { clockPhase: "round", clockSeconds: 0, clockLabel: "0:00" };
+  }
+  if (tick < roundRow.freezeEndTick) {
+    return { clockPhase: "freeze", clockSeconds: 0, clockLabel: "冻结" };
+  }
+  const plant = [...pkg.bombs]
+    .filter((bomb) => bomb.roundNumber === roundNumber && bomb.type === "planted" && bomb.tick <= tick)
+    .sort((a, b) => b.tick - a.tick)[0];
+  if (plant) {
+    const remaining = clamp(40 - (tick - plant.tick) / pkg.match.tickrate, 0, 40);
+    return { clockPhase: "bomb", clockSeconds: round(remaining, 2), clockLabel: formatClock(remaining) };
+  }
+  const remaining = clamp(115 - (tick - roundRow.freezeEndTick) / pkg.match.tickrate, 0, 115);
+  return { clockPhase: "round", clockSeconds: round(remaining, 2), clockLabel: formatClock(remaining) };
+}
+
+function eventSortWeight(type: TimelineEvent["type"]): number {
+  if (type === "bomb") return 0;
+  if (type === "kill") return 1;
+  if (type === "grenade") return 2;
+  return 3;
+}
+
+function bombLabel(pkg: DemoPackage, bomb: DemoPackage["bombs"][number]): string {
+  const actor = nameForSteamId(pkg, bomb.actorSteamId64) ?? "未知选手";
+  const labels: Record<string, string> = {
+    planted: "下包",
+    defused: "拆包",
+    exploded: "爆炸",
+    dropped: "掉包",
+    picked_up: "捡包",
+    plant_begin: "开始下包",
+    defuse_begin: "开始拆包"
+  };
+  return `${actor} ${labels[bomb.type] ?? bomb.type}`;
+}
+
+function grenadeLabel(type: string): string {
+  const labels: Record<string, string> = {
+    smoke: "烟雾弹",
+    smokegrenade: "烟雾弹",
+    flashbang: "闪光弹",
+    hegrenade: "手雷",
+    molotov: "燃烧弹",
+    incgrenade: "燃烧弹",
+    decoy: "诱饵弹"
+  };
+  return labels[normalizeWeapon(type)] ?? type;
+}
+
+function sideLabel(side: "t" | "ct"): string {
+  return side === "t" ? "进攻方" : "防守方";
+}
+
+function endReasonLabel(reason: string): string {
+  const labels: Record<string, string> = {
+    t_win: "歼灭",
+    ct_win: "歼灭",
+    target_bombed: "爆炸",
+    bomb_defused: "拆包",
+    target_saved: "时间耗尽"
+  };
+  return labels[reason] ?? reason;
+}

package/src/utils.ts

@@ -0,0 +1,133 @@
+import type { AccountSignalsV2, DemoPackage } from "@cs2dak/contract";
+
+export type BuyDeltaBuckets = NonNullable<AccountSignalsV2["combat"]["killsByBuyDelta"]>;
+export type ManStateBuckets = NonNullable<AccountSignalsV2["combat"]["killsByManState"]>;
+export type ObjectiveBuckets = AccountSignalsV2["objective"];
+export type UtilityBuckets = AccountSignalsV2["utility"];
+
+export const BUY_DELTA_EVEN_THRESHOLD = 1000;
+
+export function round(value: number, digits: number): number {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+export function formatClock(seconds: number): string {
+  const clamped = Math.max(0, Math.ceil(seconds));
+  const minutes = Math.floor(clamped / 60);
+  const remainder = clamped % 60;
+  return `${minutes}:${remainder.toString().padStart(2, "0")}`;
+}
+
+export function getOrInit<K, V>(map: Map<K, V>, key: K, create: () => V): V {
+  const existing = map.get(key);
+  if (existing) return existing;
+  const next = create();
+  map.set(key, next);
+  return next;
+}
+
+export function groupBy<T, K>(rows: T[], keyFor: (row: T) => K): Map<K, T[]> {
+  const out = new Map<K, T[]>();
+  for (const row of rows) {
+    const key = keyFor(row);
+    const bucket = out.get(key) ?? [];
+    bucket.push(row);
+    out.set(key, bucket);
+  }
+  return out;
+}
+
+export function zeroBuyDelta(): BuyDeltaBuckets {
+  return { disadvantage: 0, even: 0, advantage: 0 };
+}
+
+export function zeroManState(): ManStateBuckets {
+  return { manDown: 0, even: 0, manUp: 0 };
+}
+
+export function firstKillMap(pkg: DemoPackage): Map<number, DemoPackage["kills"][number]> {
+  const firstKillByRound = new Map<number, DemoPackage["kills"][number]>();
+  for (const kill of [...pkg.kills].sort((a, b) => a.tick - b.tick)) {
+    if (!firstKillByRound.has(kill.roundNumber)) {
+      firstKillByRound.set(kill.roundNumber, kill);
+    }
+  }
+  return firstKillByRound;
+}
+
+export function sumDamageForPlayer(pkg: DemoPackage, steamId64: string): number {
+  return pkg.damages
+    .filter((damage) => damage.attackerSteamId64 === steamId64 && damage.attackerTeamKey !== damage.victimTeamKey)
+    .reduce((sum, damage) => sum + damage.healthDamage, 0);
+}
+
+export function openingKillsForPlayer(pkg: DemoPackage, steamId64: string): number {
+  return [...firstKillMap(pkg).values()].filter((kill) => kill.killerSteamId64 === steamId64).length;
+}
+
+export function openingDeathsForPlayer(pkg: DemoPackage, steamId64: string): number {
+  return [...firstKillMap(pkg).values()].filter((kill) => kill.victimSteamId64 === steamId64).length;
+}
+
+export function multiKillRounds(kills: DemoPackage["kills"], target: number): number {
+  const counts = new Map<number, number>();
+  for (const kill of kills) {
+    counts.set(kill.roundNumber, (counts.get(kill.roundNumber) ?? 0) + 1);
+  }
+  return [...counts.values()].filter((count) => (target === 5 ? count >= 5 : count === target)).length;
+}
+
+export function clutchSplit(
+  statsCount: number | undefined,
+  statsWon: number | undefined,
+  clutches: DemoPackage["clutches"],
+  opponentCount: number
+) {
+  const rows = clutches.filter((row) => row.opponentCount === opponentCount);
+  return {
+    count: statsCount ?? rows.length,
+    won: statsWon ?? rows.filter((row) => row.won).length
+  };
+}
+
+export function clutchSplitV2(
+  count: number | undefined,
+  won: number | undefined,
+  rows: DemoPackage["clutches"],
+  opponentCount: number
+) {
+  const filtered = rows.filter((row) => row.opponentCount === opponentCount);
+  return {
+    count: count ?? filtered.length,
+    won: won ?? filtered.filter((row) => row.won).length
+  };
+}
+
+export function normalizeWeapon(weapon: string): string {
+  return weapon.toLowerCase().replace(/^weapon_/, "");
+}
+
+export function isNamedWeapon(value: string): boolean {
+  return /^[a-z_][a-z0-9_]*$/.test(value);
+}
+
+export function isUtilityWeapon(weapon: string): boolean {
+  return ["hegrenade", "inferno", "molotov", "incgrenade"].includes(normalizeWeapon(weapon));
+}
+
+export function killWeaponName(kill: DemoPackage["kills"][number]): string {
+  const active = kill.killerActiveWeapon ? normalizeWeapon(kill.killerActiveWeapon) : "";
+  return isNamedWeapon(active) ? active : normalizeWeapon(kill.weapon);
+}
+
+export function nameForSteamId(pkg: DemoPackage, steamId: string | null): string | null {
+  if (!steamId) {
+    return null;
+  }
+  return pkg.players.find((player) => player.steamId64 === steamId)?.name ?? steamId;
+}

package/src/weapons.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { displayWeaponName } from "./weapons";
+
+describe("displayWeaponName", () => {
+  it("maps raw codes to canonical display names", () => {
+    expect(displayWeaponName("ak47")).toBe("AK-47");
+    expect(displayWeaponName("m4a1_silencer")).toBe("M4A1-S");
+    expect(displayWeaponName("awp")).toBe("AWP");
+    expect(displayWeaponName("deagle")).toBe("Desert Eagle");
+  });
+
+  it("strips the weapon_ prefix and is case-insensitive", () => {
+    expect(displayWeaponName("weapon_ak47")).toBe("AK-47");
+    expect(displayWeaponName("WEAPON_AWP")).toBe("AWP");
+  });
+
+  it("collapses every knife/bayonet variant to a single label", () => {
+    expect(displayWeaponName("knife")).toBe("knife");
+    expect(displayWeaponName("knife_karambit")).toBe("knife");
+    expect(displayWeaponName("weapon_bayonet")).toBe("knife");
+  });
+
+  it("falls back to the normalized code instead of an unknown placeholder", () => {
+    expect(displayWeaponName("weapon_some_future_gun")).toBe("some_future_gun");
+  });
+
+  it("never returns a purely numeric string for a named weapon", () => {
+    for (const raw of ["ak47", "m4a1_silencer", "knife_m9_bayonet", "future_gun"]) {
+      expect(/^\d+$/.test(displayWeaponName(raw))).toBe(false);
+    }
+  });
+});