@cs2dak/core 1.0.0 → 2.0.0

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]!);
+  });
+});