@cs2dak/core 0.2.1 → 2.0.0

package/src/normalize.ts

@@ -1,158 +1,35 @@
-import { demoPackageSchema, type DemoPackage, type TeamKey } from "@cs2dak/contract";
+import { demoPackageSchema, type DemoPackage } from "@cs2dak/contract";
 
 export function parsePackageJson(text: string): unknown {
   return JSON.parse(text.replace(/\bNaN\b/g, "null"));
 }
 
-export function normalizeDemoPackage(input: unknown): DemoPackage {
-  const raw = input as Record<string, unknown>;
-  const manifest = raw.manifest as Record<string, unknown> | undefined;
-
-  if (manifest?.schemaVersion === "cs2-demo-format/1.0") {
-    return demoPackageSchema.parse(normalizeV1Package(raw));
-  }
-
-  return demoPackageSchema.parse(input);
-}
-
-function normalizeV1Package(raw: Record<string, unknown>): Record<string, unknown> {
-  const match = raw.match as Record<string, unknown>;
-  const rounds = asRecords(raw.rounds).filter((round) => numberValue(round.roundNumber) > 0);
-  const roundByNumber = new Map(rounds.map((round) => [numberValue(round.roundNumber), round]));
-
-  return {
-    manifest: {
-      ...(raw.manifest as Record<string, unknown>),
-      schemaVersion: "cs2-demo-format/2.0"
-    },
-    match: {
-      ...match,
-      durationSeconds: numberValue(match.durationSeconds) > 0 ? match.durationSeconds : undefined
-    },
-    players: raw.players,
-    rounds: rounds.map((round) => normalizeV1Round(round)),
-    playerEconomies: asRecords(raw.playerEconomies)
-      .filter((row) => numberValue(row.roundNumber) > 0)
-      .map((row) => ({ ...row, type: normalizeEconomyType(row.type) })),
-    playerStats: raw.playerStats ?? [],
-    kills: asRecords(raw.kills)
-      .filter((kill) => numberValue(kill.roundNumber) > 0)
-      .map((kill) => normalizeV1Kill(kill, roundByNumber)),
-    damages: asRecords(raw.damages)
-      .filter((row) => numberValue(row.roundNumber) > 0)
-      .map((row) => normalizeV1Damage(row, roundByNumber)),
-    blinds: asRecords(raw.blinds).filter((row) => numberValue(row.roundNumber) > 0),
-    grenades: asRecords(raw.grenades)
-      .filter((row) => numberValue(row.roundNumber) > 0)
-      .map((row) => normalizeV1Grenade(row, roundByNumber)),
-    clutches: asRecords(raw.clutches).filter((row) => numberValue(row.roundNumber) > 0)
-  };
-}
-
-function asRecords(value: unknown): Record<string, unknown>[] {
-  return Array.isArray(value) ? value.filter((row): row is Record<string, unknown> => !!row && typeof row === "object" && !Array.isArray(row)) : [];
-}
-
-function normalizeV1Round(round: Record<string, unknown>): Record<string, unknown> {
-  return {
-    ...round,
-    startTick: positiveInt(round.startTick),
-    freezeEndTick: positiveInt(round.freezeEndTick),
-    endTick: positiveInt(round.endTick),
-    teamASide: normalizeSide(round.teamASide) ?? "t",
-    teamBSide: normalizeSide(round.teamBSide) ?? "ct",
-    teamAEconomy: normalizeEconomyType(round.teamAEconomy),
-    teamBEconomy: normalizeEconomyType(round.teamBEconomy),
-    winnerSide: normalizeSide(round.winnerSide) ?? sideForTeam(round.winnerTeamKey, round) ?? "t"
-  };
-}
-
-function normalizeV1Kill(kill: Record<string, unknown>, rounds: Map<number, Record<string, unknown>>): Record<string, unknown> {
-  const round = rounds.get(numberValue(kill.roundNumber));
-  return {
-    ...kill,
-    tick: positiveInt(kill.tick),
-    killerTeamKey: normalizeTeamKey(kill.killerTeamKey),
-    victimTeamKey: normalizeTeamKey(kill.victimTeamKey) ?? "teamA",
-    killerSide: normalizeSide(kill.killerSide) ?? sideForTeam(kill.killerTeamKey, round),
-    victimSide: normalizeSide(kill.victimSide) ?? sideForTeam(kill.victimTeamKey, round) ?? "t",
-    killerPosition: sanitizeNullablePosition(kill.killerPosition),
-    victimPosition: sanitizePosition(kill.victimPosition)
-  };
-}
-
-function normalizeV1Damage(row: Record<string, unknown>, rounds: Map<number, Record<string, unknown>>): Record<string, unknown> {
-  const round = rounds.get(numberValue(row.roundNumber));
-  return {
-    ...row,
-    tick: positiveInt(row.tick),
-    weapon: typeof row.weapon === "string" && row.weapon.length > 0 ? row.weapon : "unknown",
-    attackerTeamKey: normalizeTeamKey(row.attackerTeamKey),
-    victimTeamKey: normalizeTeamKey(row.victimTeamKey) ?? "teamA",
-    attackerSide: normalizeSide(row.attackerSide) ?? sideForTeam(row.attackerTeamKey, round),
-    victimSide: normalizeSide(row.victimSide) ?? sideForTeam(row.victimTeamKey, round) ?? "t",
-    attackerPosition: sanitizeNullablePosition(row.attackerPosition),
-    victimPosition: sanitizeNullablePosition(row.victimPosition) ?? undefined
-  };
-}
-
-function normalizeV1Grenade(row: Record<string, unknown>, rounds: Map<number, Record<string, unknown>>): Record<string, unknown> {
-  const round = rounds.get(numberValue(row.roundNumber));
-  const teamKey = normalizeTeamKey(row.throwerTeamKey ?? row.teamKey);
-  return {
-    roundNumber: row.roundNumber,
-    tick: positiveInt(row.effectTick ?? row.throwTick ?? row.tick),
-    steamId64: row.throwerSteamId64 ?? row.steamId64 ?? null,
-    teamKey,
-    side: normalizeSide(row.throwerSide ?? row.side) ?? sideForTeam(teamKey, round),
-    grenadeType: typeof row.grenade === "string" && row.grenade.length > 0 ? row.grenade : row.grenadeType ?? "unknown",
-    eventType: row.eventType ?? "effect",
-    position: sanitizeNullablePosition(row.effectPosition ?? row.throwPosition ?? row.position)
-  };
-}
+/**
+ * 已校验过的 DemoPackage 打标，避免对同一对象重复跑整包 zod 解析。
+ * 单场 facts 抽取里 buildOpeningTrails（每选手一次）/ workspace / 各 extract* 都会
+ * 再调 normalizeDemoPackage(pkg)；已规范化对象直接复用即可（zod parse 对已验证对象幂等）。
+ */
+const normalized = new WeakSet<object>();
 
-function sideForTeam(teamKey: unknown, round: Record<string, unknown> | undefined): "t" | "ct" | null {
-  const team = normalizeTeamKey(teamKey);
-  if (!team || !round) {
-    return null;
-  }
-  return normalizeSide(team === "teamA" ? round.teamASide : round.teamBSide);
-}
-
-function normalizeTeamKey(value: unknown): TeamKey | null {
-  return value === "teamA" || value === "teamB" ? value : null;
-}
-
-function normalizeSide(value: unknown): "t" | "ct" | null {
-  return value === "t" || value === "ct" ? value : null;
-}
-
-function normalizeEconomyType(value: unknown): "pistol" | "eco" | "semi" | "force" | "full" | "conversion" {
-  return value === "pistol" || value === "eco" || value === "semi" || value === "force" || value === "full" || value === "conversion" ? value : "full";
-}
+/**
+ * 重型数组（replay ~17MB / duels ~11MB）排除在 zod 校验之外：上游 cs2-demo-format 的
+ * replay/duels schema 是纯校验（无 transform/refine/coerce），JSON.parse 出来即最终形状，
+ * 跑 zod 只是把它们整张深拷贝一遍——这正是单场导入的内存峰值主因（graph#1 原图 +
+ * graph#2 zod 拷贝同时存在）。校验其余小/中型 section，replay/duels 按引用挂回，
+ * 避免百 MB 级深拷贝，单场峰值大致砍半。
+ */
+const leanSchema = demoPackageSchema.omit({ replay: true, duels: true });
 
-function numberValue(value: unknown): number {
-  return typeof value === "number" && Number.isFinite(value) ? value : 0;
-}
-
-function positiveInt(value: unknown): number {
-  return Math.max(1, Math.trunc(numberValue(value)));
-}
-
-function sanitizeNullablePosition(value: unknown): { x: number; y: number; z: number } | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  const point = value as Record<string, unknown>;
-  const x = numberValue(point.x);
-  const y = numberValue(point.y);
-  const z = numberValue(point.z);
-  if (x === 0 && y === 0 && z === 0) {
-    return null;
+export function normalizeDemoPackage(input: unknown): DemoPackage {
+  if (typeof input === "object" && input !== null && normalized.has(input)) {
+    return input as DemoPackage;
   }
-  return { x, y, z };
-}
-
-function sanitizePosition(value: unknown): { x: number; y: number; z: number } {
-  return sanitizeNullablePosition(value) ?? { x: 0, y: 0, z: 0 };
+  const raw = (input ?? {}) as { replay?: unknown; duels?: unknown };
+  const { replay, duels } = raw;
+  // leanSchema 会 strip 掉 replay/duels；校验完按引用挂回原数组，不深拷贝。
+  const pkg = leanSchema.parse(input) as DemoPackage;
+  if (replay !== undefined) (pkg as { replay?: unknown }).replay = replay;
+  if (duels !== undefined) (pkg as { duels?: unknown }).duels = duels;
+  normalized.add(pkg);
+  return pkg;
 }

package/src/qa.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage, PackageDamage } from "@cs2dak/contract";
+import { activeDamages } from "./utils.js";
+import { buildQaReport, demoSourceAvailability } from "./qa.js";
+
+function damage(tick: number): PackageDamage {
+  return {
+    roundNumber: 1,
+    tick,
+    attackerIndex: 0,
+    victimIndex: 1,
+    weapon: "ak47",
+    hitgroup: "head",
+    healthDamage: 12,
+    healthDamageRaw: 12,
+    armorDamage: 0,
+    victimHealthBefore: 100,
+    victimArmorAfter: 100,
+    attackerPosition: { x: 0, y: 0, z: 0 },
+    victimPosition: { x: 100, y: 0, z: 0 }
+  };
+}
+
+function pkg(overrides: Partial<DemoPackage>): DemoPackage {
+  return {
+    manifest: {
+      schemaVersion: "cs2-demo-format/3.0",
+      exporter: { name: "test", version: "0" },
+      parser: { name: "test", version: "0" },
+      demo: { hash: null, sourceFileName: null },
+      mapName: "de_mirage",
+      tickrate: 64,
+      exportedAt: "2026-01-01T00:00:00Z",
+      files: {
+        match: "match.json",
+        players: "players.json",
+        rounds: "rounds.json",
+        playerStats: "player-stats.json",
+        playerEconomies: "player-economies.json",
+        kills: "kills.json",
+        damages: "damages.json",
+        blinds: "blinds.json",
+        bombs: "bombs.json",
+        grenades: "grenades.json",
+        clutches: "clutches.json"
+      }
+    },
+    match: {
+      mapName: "de_mirage",
+      tickrate: 64,
+      durationSeconds: 120,
+      serverName: null,
+      source: "test",
+      teamA: { teamKey: "teamA", name: "A", score: 1 },
+      teamB: { teamKey: "teamB", name: "B", score: 0 }
+    },
+    players: [
+      { steamId64: "76561198000000001", name: "A", teamKey: "teamA" },
+      { steamId64: "76561198000000002", name: "B", teamKey: "teamB" }
+    ],
+    rounds: [{
+      roundNumber: 1,
+      startTick: 1,
+      freezeEndTick: 100,
+      endTick: 500,
+      winnerTeamKey: "teamA",
+      winnerSide: "T",
+      teamASide: "T",
+      teamBSide: "CT",
+      endReason: "target_bombed",
+      durationSeconds: 10
+    }],
+    playerEconomies: [],
+    playerStats: [],
+    kills: [],
+    damages: [],
+    blinds: [],
+    bombs: [],
+    grenades: [],
+    clutches: [],
+    ...overrides
+  } as DemoPackage;
+}
+
+describe("buildQaReport", () => {
+  it("reports v3 required event families as available when a valid match has zero events", () => {
+    const availability = demoSourceAvailability(pkg({ kills: [], damages: [], blinds: [], bombs: [], grenades: [], clutches: [] }));
+
+    expect(availability).toMatchObject({
+      damages: "available",
+      bombs: "available",
+      utility: "available",
+      clutches: "available",
+      richKills: "available",
+    });
+  });
+
+  it("accepts pre-freeze damage rows but excludes them from active damage analytics", () => {
+    const demo = pkg({ damages: [damage(50), damage(120)] });
+
+    expect(buildQaReport(demo).issues).not.toContainEqual(expect.objectContaining({
+      code: "damages.tick_outside_round"
+    }));
+    expect(activeDamages(demo).map((row) => row.tick)).toEqual([120]);
+  });
+
+  it("still reports damage rows before the round start", () => {
+    const demo = pkg({ damages: [damage(0)] });
+
+    expect(buildQaReport(demo).issues).toContainEqual(expect.objectContaining({
+      severity: "error",
+      code: "damages.tick_outside_round"
+    }));
+  });
+});

package/src/qa.ts

@@ -3,11 +3,26 @@ import { isNamedWeapon, normalizeWeapon, round } from "./utils.js";
 
 export type ScoreboardFieldAvailability = PlayerScoreboardRow["fieldAvailability"];
 
+export type DemoSourceAvailability = ScoreboardFieldAvailability & {
+  utility: "available";
+  clutches: "available";
+};
+
 export function buildQaReport(pkg: DemoPackage): QaReport {
   const issues: QaIssue[] = [];
   const roundNumbers = pkg.rounds.map((round) => round.roundNumber).sort((a, b) => a - b);
   const roundsByNumber = new Map(pkg.rounds.map((round) => [round.roundNumber, round]));
-  const playerIds = new Set(pkg.players.map((player) => player.steamId64));
+  // 3.0.3+: 非最终回合的事件窗口延伸到下一回合 startTick 前
+  const sortedRounds = [...pkg.rounds].sort((a, b) => a.roundNumber - b.roundNumber);
+  const eventEndTickByRound = new Map<number, number>();
+  for (let i = 0; i < sortedRounds.length; i++) {
+    const current = sortedRounds[i];
+    const next = sortedRounds[i + 1];
+    eventEndTickByRound.set(
+      current.roundNumber,
+      next ? next.startTick - 1 : current.endTick
+    );
+  }
 
   for (let i = 0; i < roundNumbers.length; i += 1) {
     if (roundNumbers[i] !== i + 1) {
@@ -64,7 +79,8 @@ export function buildQaReport(pkg: DemoPackage): QaReport {
       return;
     }
     const minTick = allowFreeze ? roundRow.startTick : roundRow.freezeEndTick;
-    if (tick < minTick || tick > roundRow.endTick) {
+    const eventEnd = eventEndTickByRound.get(roundNumber) ?? roundRow.endTick;
+    if (tick < minTick || tick > eventEnd) {
       issues.push({
         severity: "error",
         code: `${kind}.tick_outside_round`,
@@ -86,25 +102,25 @@ export function buildQaReport(pkg: DemoPackage): QaReport {
 
   pkg.kills.forEach((kill, index) => {
     checkEventTick("kills", kill.roundNumber, kill.tick, index);
-    if (kill.killerSteamId64 && !playerIds.has(kill.killerSteamId64)) {
+    if (kill.killerIndex !== null && kill.killerIndex >= pkg.players.length) {
       issues.push({
         severity: "warning",
         code: "kill.unknown_killer",
-        message: `Killer ${kill.killerSteamId64} is not present in players.json.`,
+        message: `Killer playerIndex ${kill.killerIndex} is out of range (players.length=${pkg.players.length}).`,
         path: "kills"
       });
     }
-    if (!playerIds.has(kill.victimSteamId64)) {
+    if (kill.victimIndex >= pkg.players.length) {
       issues.push({
         severity: "error",
         code: "kill.unknown_victim",
-        message: `Victim ${kill.victimSteamId64} is not present in players.json.`,
+        message: `Victim playerIndex ${kill.victimIndex} is out of range (players.length=${pkg.players.length}).`,
         path: "kills"
       });
     }
   });
 
-  pkg.damages.forEach((damage, index) => checkEventTick("damages", damage.roundNumber, damage.tick, index));
+  pkg.damages.forEach((damage, index) => checkEventTick("damages", damage.roundNumber, damage.tick, index, true));
   pkg.blinds.forEach((blind, index) => checkEventTick("blinds", blind.roundNumber, blind.tick, index));
   pkg.grenades.forEach((grenade, index) => {
     checkEventTick("grenades", grenade.roundNumber, grenade.throwTick, index);
@@ -117,11 +133,11 @@ export function buildQaReport(pkg: DemoPackage): QaReport {
     const events = bombEventsByRound.get(bomb.roundNumber) ?? [];
     events.push(bomb);
     bombEventsByRound.set(bomb.roundNumber, events);
-    if (bomb.actorSteamId64 && !playerIds.has(bomb.actorSteamId64)) {
+    if (bomb.actorIndex !== null && bomb.actorIndex >= pkg.players.length) {
       issues.push({
         severity: "warning",
         code: "bomb.unknown_actor",
-        message: `Bomb actor ${bomb.actorSteamId64} is not present in players.json.`,
+        message: `Bomb actor playerIndex ${bomb.actorIndex} is out of range (players.length=${pkg.players.length}).`,
         path: "bombs"
       });
     }
@@ -166,13 +182,32 @@ export function buildQaReport(pkg: DemoPackage): QaReport {
 }
 
 export function fieldAvailability(pkg: DemoPackage): ScoreboardFieldAvailability {
+  const availability = demoSourceAvailability(pkg);
+  return {
+    playerStats: availability.playerStats,
+    economy: availability.economy,
+    rounds: availability.rounds,
+    richKills: availability.richKills,
+    damages: availability.damages,
+    bombs: availability.bombs,
+  };
+}
+
+/**
+ * Source capability is determined by the validated v3 contract, never by
+ * whether a particular match happened to produce an event. The loader rejects
+ * absent required files before this function can run.
+ */
+export function demoSourceAvailability(pkg: DemoPackage): DemoSourceAvailability {
   return {
-    playerStats: pkg.playerStats.length > 0 ? "available" : "missing",
-    economy: pkg.playerEconomies.length > 0 ? "available" : "missing",
-    rounds: pkg.rounds.length > 0 ? "available" : "missing",
+    playerStats: "available",
+    economy: "available",
+    rounds: "available",
     richKills: richKillAvailability(pkg),
-    damages: pkg.damages.length > 0 ? "available" : "missing",
-    bombs: pkg.bombs.length > 0 ? "available" : "missing"
+    damages: "available",
+    bombs: "available",
+    utility: "available",
+    clutches: "available",
   };
 }
 
@@ -189,7 +224,8 @@ export function fieldConfidence(availability: ScoreboardFieldAvailability): numb
 }
 
 function richKillAvailability(pkg: DemoPackage): ScoreboardFieldAvailability["richKills"] {
-  if (pkg.kills.length === 0) return "missing";
+  // A legal empty kills.json is an observed zero, not an unavailable source.
+  if (pkg.kills.length === 0) return "available";
   const hasFlags = pkg.kills.some((kill) => "throughSmoke" in kill && "noScope" in kill && "penetratedObjects" in kill);
   const activeWeaponsAreNames = pkg.kills.some((kill) => kill.killerActiveWeapon && isNamedWeapon(normalizeWeapon(kill.killerActiveWeapon)));
   if (hasFlags && activeWeaponsAreNames) return "available";

package/src/radar-field.test.ts

@@ -0,0 +1,79 @@
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { buildRadarFieldGrid } from "@cs2dak/maps";
+import { RADAR_FIELD_BASES, type DemoPackage } from "@cs2dak/contract";
+import { loadDemoPackageFromZip } from "./loader.js";
+import { buildMatchRadarField, aggregateRadarFields } from "./radar-field.js";
+
+let pkg: DemoPackage;
+
+beforeAll(async () => {
+  const zip = await readFile(
+    fileURLToPath(new URL("../../../fixtures/input/sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip", import.meta.url))
+  );
+  pkg = await loadDemoPackageFromZip(zip);
+});
+
+function radarFieldDigest(fields: ReturnType<typeof buildMatchRadarField>): string {
+  const hash = createHash("sha256");
+  for (const field of fields) {
+    hash.update(field.scope.team ?? "");
+    hash.update(Buffer.from(field.denomCt.buffer, field.denomCt.byteOffset, field.denomCt.byteLength));
+    hash.update(Buffer.from(field.denomT.buffer, field.denomT.byteOffset, field.denomT.byteLength));
+    for (const base of RADAR_FIELD_BASES) {
+      for (const row of field.fields[base]) {
+        hash.update(Buffer.from(row.buffer, row.byteOffset, row.byteLength));
+      }
+    }
+  }
+  return hash.digest("hex");
+}
+
+describe("buildMatchRadarField", () => {
+  it("每场产出两份按队归属的加性场贡献", () => {
+    const grid = buildRadarFieldGrid("de_ancient");
+    expect(grid).not.toBeNull();
+    const fields = buildMatchRadarField(pkg, { matchId: "m", grid: grid!, bvh: null });
+    expect(fields).toHaveLength(2);
+
+    for (const f of fields) {
+      expect(f.scope.kind).toBe("team");
+      expect(f.triAvailability).toBe("none"); // 无 .tri
+      expect(f.denomCt).toHaveLength(f.maxSec);
+      expect(f.denomT).toHaveLength(f.maxSec);
+      expect(f.fields.ctVis).toHaveLength(f.maxSec);
+      expect(f.fields.ctAim).toHaveLength(f.maxSec);
+      expect(f.fields.ctSound).toHaveLength(f.maxSec);
+      expect(f.fields.ctVis[0]!).toHaveLength(f.grid.cells.length);
+    }
+    // 至少有一个回合被采样（denom 有非零），且有视野/位置计数。
+    const totalDenom = fields.reduce((s, f) => s + f.denomCt.reduce((a, b) => a + b, 0), 0);
+    expect(totalDenom).toBeGreaterThan(0);
+    const totalVis = fields.reduce((s, f) => s + f.fields.tPres.reduce((a, row) => a + row.reduce((x, y) => x + y, 0), 0), 0);
+    expect(totalVis).toBeGreaterThan(0);
+    const totalSound = fields.reduce((s, f) => s + f.fields.tSound.reduce((a, row) => a + row.reduce((x, y) => x + y, 0), 0), 0);
+    expect(totalSound).toBeGreaterThan(0);
+  });
+
+  it("sample 输出指纹保持稳定", () => {
+    const grid = buildRadarFieldGrid("de_ancient")!;
+    const fields = buildMatchRadarField(pkg, { matchId: "snapshot", grid, bvh: null });
+    expect(radarFieldDigest(fields)).toBe("0405c90078d54c7ce4a391a1140a9cf2dc6bd3c9a28b4aace3be5d5be3bc8319");
+  });
+
+  it("aggregateRadarFields 是逐元素加法（联赛基线 = 各贡献之和）", () => {
+    const grid = buildRadarFieldGrid("de_ancient")!;
+    const fields = buildMatchRadarField(pkg, { matchId: "m", grid, bvh: null });
+    const league = aggregateRadarFields(fields, { kind: "league", team: null })!;
+    expect(league.scope.kind).toBe("league");
+
+    // 抽查某秒某格：聚合 = 两份之和。
+    const s = 20;
+    const g = Math.floor(grid.cells.length / 2);
+    const expected = fields[0]!.fields.ctVis[s]![g]! + fields[1]!.fields.ctVis[s]![g]!;
+    expect(league.fields.ctVis[s]![g]!).toBe(expected);
+    expect(league.denomCt[s]!).toBe(fields[0]!.denomCt[s]! + fields[1]!.denomCt[s]!);
+  });
+});