madden-fantasy-extractor 0.2.0

package/test/incremental.test.js

@@ -0,0 +1,147 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { selectGamesToCapture, selectReadyGames, selectPendingGames, unionCapturedKeys, seasonCaptureKey } from '../src/lib/incremental.js';
+import { gameKey } from '../src/extract/games.js';
+
+function game(seasonWeekType, seasonWeek, home, away, gameStatus = 'HomeWon') {
+  return { seasonWeekType, seasonWeek, homeExternalTeamId: home, awayExternalTeamId: away, gameStatus };
+}
+
+test('selectGamesToCapture: fullMode returns every game unfiltered', () => {
+  const games = [
+    game('RegularSeason', 0, 10, 20, 'HomeWon'),
+    game('RegularSeason', 1, 10, 30, 'Unplayed'),
+  ];
+  const result = selectGamesToCapture(games, { fullMode: true, seasonIndex: 0, alreadyCapturedKeys: new Set() });
+  assert.deepEqual(result, games);
+});
+
+test('selectGamesToCapture: normal mode excludes undecided games', () => {
+  const games = [
+    game('RegularSeason', 0, 10, 20, 'HomeWon'),
+    game('RegularSeason', 1, 10, 30, 'Unplayed'),
+    game('RegularSeason', 2, 10, 40, 'Unscheduled'),
+  ];
+  const result = selectGamesToCapture(games, { fullMode: false, seasonIndex: 0, alreadyCapturedKeys: new Set() });
+  assert.equal(result.length, 1);
+  assert.equal(result[0].seasonWeek, 0);
+});
+
+test('selectGamesToCapture: normal mode excludes games already in the watermark', () => {
+  const g1 = game('RegularSeason', 0, 10, 20, 'HomeWon');
+  const g2 = game('RegularSeason', 1, 10, 30, 'AwayWon');
+  const alreadyCapturedKeys = new Set([seasonCaptureKey(0, g1)]);
+
+  const result = selectGamesToCapture([g1, g2], { fullMode: false, seasonIndex: 0, alreadyCapturedKeys });
+  assert.equal(result.length, 1);
+  assert.equal(result[0].seasonWeek, 1);
+});
+
+test('selectGamesToCapture: a Tie counts as decided', () => {
+  const g = game('RegularSeason', 0, 10, 20, 'Tie');
+  const result = selectGamesToCapture([g], { fullMode: false, seasonIndex: 0, alreadyCapturedKeys: new Set() });
+  assert.equal(result.length, 1);
+});
+
+test('unionCapturedKeys: adds new keys without dropping existing ones', () => {
+  const g1 = game('RegularSeason', 0, 10, 20);
+  const g2 = game('RegularSeason', 1, 10, 30);
+  const existing = new Set([seasonCaptureKey(0, g1)]);
+
+  const next = unionCapturedKeys(existing, [g2], 0);
+  assert.equal(next.size, 2);
+  assert.ok(next.has(seasonCaptureKey(0, g1)));
+  assert.ok(next.has(seasonCaptureKey(0, g2)));
+});
+
+test('unionCapturedKeys: does not mutate the input set', () => {
+  const g1 = game('RegularSeason', 0, 10, 20);
+  const existing = new Set();
+  unionCapturedKeys(existing, [g1], 0);
+  assert.equal(existing.size, 0);
+});
+
+test('seasonCaptureKey: disambiguates an identical matchup/week across two seasons', () => {
+  // The payload's own gameKey is season-agnostic by design (games.js) — sufficient
+  // within one extraction run, but two different seasons CAN report the same
+  // week-type/index/home/away combination. seasonCaptureKey must not collide here,
+  // or a new season's opening week would be silently treated as "already captured"
+  // from a stale watermark left over from the prior season.
+  const g = game('RegularSeason', 0, 10, 20);
+  const season0Key = seasonCaptureKey(0, g);
+  const season1Key = seasonCaptureKey(1, g);
+  assert.notEqual(season0Key, season1Key);
+
+  // and confirm the underlying gameKey really is identical across both calls, i.e.
+  // the disambiguation is coming from the season prefix, not from gameKey itself
+  assert.equal(gameKey(g), gameKey(g));
+});
+
+test('a freshly-decided game that produced no player stats yet is retried next run', () => {
+  // Simulates the week-lag scenario: a game is decided (selected this run) but
+  // produced zero player_game_stat rows (caller would compute readyGames as empty
+  // for it), so it must NOT be added to the watermark, and must be selected again
+  // on the next run.
+  const g = game('RegularSeason', 5, 10, 20, 'HomeWon');
+  const alreadyCapturedKeys = new Set(); // nothing marked captured — simulates "not ready" outcome
+
+  const selected = selectGamesToCapture([g], { fullMode: false, seasonIndex: 0, alreadyCapturedKeys });
+  assert.equal(selected.length, 1, 'game is selected again since it was never added to the watermark');
+});
+
+test('selectReadyGames: a RegularSeason game is only ready once it produced a player_game_stat row', () => {
+  const decidedNoStats = game('RegularSeason', 5, 10, 20, 'HomeWon');
+  const decidedWithStats = game('RegularSeason', 4, 10, 20, 'HomeWon');
+  const playerGameStats = [{ gameKey: gameKey(decidedWithStats), statCategoryKey: 'pass_yards', value: 200 }];
+
+  const ready = selectReadyGames([decidedNoStats, decidedWithStats], playerGameStats);
+  assert.equal(ready.length, 1);
+  assert.equal(ready[0].seasonWeek, 4);
+});
+
+test('selectReadyGames: PreSeason games are ready as soon as decided, with zero player stats', () => {
+  // The carve-out: confirmed against a real save that PreSeason games NEVER produce
+  // player_game_stat rows in this data model, so gating on stat presence would loop
+  // them forever. Decided is both correct and the only signal available here.
+  const decidedPreseason = game('PreSeason', 0, 10, 20, 'HomeWon');
+  const undecidedPreseason = game('PreSeason', 1, 10, 30, 'Unplayed');
+
+  const ready = selectReadyGames([decidedPreseason, undecidedPreseason], []);
+  assert.equal(ready.length, 1);
+  assert.equal(ready[0].seasonWeek, 0);
+});
+
+test('selectReadyGames: a game producing stats does not make an unrelated game ready', () => {
+  const g1 = game('RegularSeason', 0, 10, 20, 'HomeWon');
+  const g2 = game('RegularSeason', 1, 10, 30, 'HomeWon');
+  const playerGameStats = [{ gameKey: gameKey(g1), statCategoryKey: 'pass_yards', value: 200 }];
+
+  const ready = selectReadyGames([g1, g2], playerGameStats);
+  assert.deepEqual(ready.map((g) => g.seasonWeek), [0]);
+});
+
+test('selectPendingGames: the exact complement of selectReadyGames', () => {
+  const ready1 = game('RegularSeason', 0, 10, 20, 'HomeWon');
+  const stillWaiting = game('RegularSeason', 1, 10, 30, 'HomeWon');
+  const playerGameStats = [{ gameKey: gameKey(ready1), statCategoryKey: 'pass_yards', value: 200 }];
+
+  const pending = selectPendingGames([ready1, stillWaiting], playerGameStats);
+  assert.equal(pending.length, 1);
+  assert.equal(pending[0].seasonWeek, 1);
+});
+
+test('selectPendingGames: empty when every included game is ready', () => {
+  const g1 = game('RegularSeason', 0, 10, 20, 'HomeWon');
+  const g2 = game('PreSeason', 0, 10, 20, 'HomeWon'); // ready via the PreSeason carve-out
+  const playerGameStats = [{ gameKey: gameKey(g1), statCategoryKey: 'pass_yards', value: 200 }];
+
+  const pending = selectPendingGames([g1, g2], playerGameStats);
+  assert.deepEqual(pending, []);
+});
+
+test('selectPendingGames: every game pending when none produced stats yet', () => {
+  const g1 = game('RegularSeason', 0, 10, 20, 'HomeWon');
+  const g2 = game('RegularSeason', 1, 10, 30, 'AwayWon');
+  const pending = selectPendingGames([g1, g2], []);
+  assert.equal(pending.length, 2);
+});

package/test/player-game-stats.test.js

@@ -0,0 +1,85 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractPlayerGameStats } from '../src/extract/player-game-stats.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+import { gameKey } from '../src/extract/games.js';
+
+test('zero and missing stat values are skipped; nonzero values are kept', async () => {
+  const teamTable = fakeTable('Team', [fakeRecord({ TeamIndex: 0 }), fakeRecord({ TeamIndex: 1 })]);
+
+  const seasonGame = fakeRecord(
+    { SeasonWeekType: 'RegularSeason', SeasonWeek: 0 },
+    {
+      HomeTeam: { tableId: teamTable._id, rowNumber: 0 },
+      AwayTeam: { tableId: teamTable._id, rowNumber: 1 },
+    },
+  );
+  const seasonGameTable = fakeTable('SeasonGame', [seasonGame]);
+
+  // PASSYARDS/PASSTDS nonzero, RECEIVEYARDS explicitly 0, RUSHTDS missing entirely —
+  // all three should behave identically (skipped) except the two nonzero fields.
+  const statRow = fakeRecord(
+    { PASSYARDS: 260, RECEIVEYARDS: 0, RUSHTDS: undefined, PASSTDS: 1 },
+    { SeasonGame: { tableId: seasonGameTable._id, rowNumber: 0 } },
+  );
+  const statTable = fakeTable('GameOffensiveStats', [statRow]);
+
+  const wrapper = fakeRecord({}, { GameStats0: { tableId: statTable._id, rowNumber: 0 } });
+  const wrapperTable = fakeTable('GameStats[]', [wrapper]);
+
+  const playerRecord = fakeRecord(
+    { PresentationId: 999 },
+    { GameStats: { tableId: wrapperTable._id, rowNumber: 0 } },
+  );
+  const player = { externalPlayerId: 999, _record: playerRecord };
+
+  const franchise = fakeFranchise([teamTable, seasonGameTable, statTable, wrapperTable]);
+  const indexTeamsByTeamIndex = new Map([
+    [0, { externalTeamId: 10, teamIndex: 0 }],
+    [1, { externalTeamId: 20, teamIndex: 1 }],
+  ]);
+  const key = gameKey({ seasonWeekType: 'RegularSeason', seasonWeek: 0, homeExternalTeamId: 10, awayExternalTeamId: 20 });
+  const gamesByKey = new Map([[key, {}]]);
+
+  const rows = await extractPlayerGameStats(franchise, { players: [player], gamesByKey, indexTeamsByTeamIndex });
+
+  const byCategory = new Map(rows.map((r) => [r.statCategoryKey, r.value]));
+  assert.equal(rows.length, 2, 'only the two nonzero categories should be emitted');
+  assert.equal(byCategory.get('pass_yards'), 260);
+  assert.equal(byCategory.get('pass_tds'), 1);
+  assert.equal(byCategory.has('rec_yards'), false, 'explicit zero value must be skipped');
+  assert.equal(byCategory.has('rush_tds'), false, 'missing/undefined value must be skipped');
+});
+
+test('a player with every category zero produces no rows for that game', async () => {
+  const teamTable = fakeTable('Team', [fakeRecord({ TeamIndex: 0 }), fakeRecord({ TeamIndex: 1 })]);
+  const seasonGame = fakeRecord(
+    { SeasonWeekType: 'RegularSeason', SeasonWeek: 0 },
+    {
+      HomeTeam: { tableId: teamTable._id, rowNumber: 0 },
+      AwayTeam: { tableId: teamTable._id, rowNumber: 1 },
+    },
+  );
+  const seasonGameTable = fakeTable('SeasonGame', [seasonGame]);
+
+  const statRow = fakeRecord(
+    { PASSYARDS: 0, PASSTDS: 0, PASSATTEMPTS: 0 },
+    { SeasonGame: { tableId: seasonGameTable._id, rowNumber: 0 } },
+  );
+  const statTable = fakeTable('GameOffensiveStats', [statRow]);
+  const wrapper = fakeRecord({}, { GameStats0: { tableId: statTable._id, rowNumber: 0 } });
+  const wrapperTable = fakeTable('GameStats[]', [wrapper]);
+  const playerRecord = fakeRecord({ PresentationId: 1 }, { GameStats: { tableId: wrapperTable._id, rowNumber: 0 } });
+  const player = { externalPlayerId: 1, _record: playerRecord };
+
+  const franchise = fakeFranchise([teamTable, seasonGameTable, statTable, wrapperTable]);
+  const indexTeamsByTeamIndex = new Map([
+    [0, { externalTeamId: 10, teamIndex: 0 }],
+    [1, { externalTeamId: 20, teamIndex: 1 }],
+  ]);
+  const key = gameKey({ seasonWeekType: 'RegularSeason', seasonWeek: 0, homeExternalTeamId: 10, awayExternalTeamId: 20 });
+  const gamesByKey = new Map([[key, {}]]);
+
+  const rows = await extractPlayerGameStats(franchise, { players: [player], gamesByKey, indexTeamsByTeamIndex });
+  assert.deepEqual(rows, []);
+});

package/test/player-week-status.test.js

@@ -0,0 +1,173 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractPlayerWeekStatus } from '../src/extract/player-week-status.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+function game(seasonWeekType, seasonWeek, homeExternalTeamId, awayExternalTeamId) {
+  return { seasonWeekType, seasonWeek, homeExternalTeamId, awayExternalTeamId };
+}
+
+function fakePlayer({ externalPlayerId, teamIndex, contractStatus = 'Signed', injuryStatus = 'Uninjured', gameStatsWrapper = null }) {
+  const refs = {};
+  if (gameStatsWrapper) refs.GameStats = { tableId: gameStatsWrapper._id, rowNumber: 0 };
+  const record = fakeRecord(
+    {
+      PresentationId: externalPlayerId,
+      ContractStatus: contractStatus,
+      InjuryStatus: injuryStatus,
+      InjuryType: null,
+      InjurySeverity: null,
+      MinInjuryDuration: 0,
+      MaxInjuryDuration: 0,
+      IsInjuredReserve: false,
+      CurrentYearSeasonEndingInjuryWeek: 30,
+    },
+    refs,
+  );
+  return { externalPlayerId, teamIndex, _record: record };
+}
+
+// Builds a GameStats[] wrapper table pointing at one stat row, which itself points
+// at a SeasonGame row for the given week — the chain hasStatRowForWeek walks.
+function fakeGameStatsChain(weekType, weekIndex) {
+  const seasonGame = fakeRecord({ SeasonWeekType: weekType, SeasonWeek: weekIndex });
+  const seasonGameTable = fakeTable('SeasonGame', [seasonGame]);
+  const statRow = fakeRecord({}, { SeasonGame: { tableId: seasonGameTable._id, rowNumber: 0 } });
+  const statTable = fakeTable('GameOffensiveStats', [statRow]);
+  const wrapper = fakeRecord({}, { GameStats0: { tableId: statTable._id, rowNumber: 0 } });
+  const wrapperTable = fakeTable('GameStats[]', [wrapper]);
+  return { wrapperTable, extraTables: [seasonGameTable, statTable] };
+}
+
+function byWeekIndex(rows, weekIndex) {
+  return rows.filter((r) => r.weekIndex === weekIndex);
+}
+
+test('emits both a predictive (current week) and retrospective (completed week) row', async () => {
+  const { wrapperTable, extraTables } = fakeGameStatsChain('RegularSeason', 12);
+  const player = fakePlayer({ externalPlayerId: 1, teamIndex: 0, gameStatsWrapper: wrapperTable });
+
+  const games = [game('RegularSeason', 12, 10, 20), game('RegularSeason', 13, 10, 30)];
+  const franchise = fakeFranchise([wrapperTable, ...extraTables]);
+  const clock = { stage: 'NFLSeason', weekType: 'RegularSeason', weekIndex: 13 };
+  const indexTeamsByTeamIndex = new Map([[0, { externalTeamId: 10, teamIndex: 0 }]]);
+
+  const rows = await extractPlayerWeekStatus(franchise, { players: [player], games, clock, indexTeamsByTeamIndex });
+  assert.equal(rows.length, 2);
+
+  const retrospective = byWeekIndex(rows, 12)[0];
+  assert.equal(retrospective.status, 'active'); // confirmed played, via the GameStats chain
+
+  const predictive = byWeekIndex(rows, 13)[0];
+  assert.equal(predictive.status, 'active'); // healthy + rostered + team plays week 13 -> predicted active
+});
+
+test('predictive row is available at weekIndex 0 (no prior-week dependency), unlike retrospective', async () => {
+  const franchise = fakeFranchise([]);
+  const clock = { stage: 'NFLSeason', weekType: 'RegularSeason', weekIndex: 0 };
+  const rows = await extractPlayerWeekStatus(franchise, {
+    players: [fakePlayer({ externalPlayerId: 1, teamIndex: 0 })],
+    games: [game('PreSeason', 2, 10, 20), game('RegularSeason', 0, 10, 20)],
+    clock,
+    indexTeamsByTeamIndex: new Map([[0, { externalTeamId: 10, teamIndex: 0 }]]),
+  });
+  // Only the predictive row — no completed week exists yet at weekIndex 0, and the
+  // PreSeason->RegularSeason boundary is confirmed-ambiguous (see module header).
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].weekType, 'RegularSeason');
+  assert.equal(rows[0].weekIndex, 0);
+  assert.equal(rows[0].status, 'active');
+});
+
+test('predictive row never reports inactive — healthy+rostered+scheduled always reads active', async () => {
+  // No GameStats chain at all for this player (as if none has ever been resolved) —
+  // under retrospective logic this would be 'inactive', but predictive mode can't
+  // know that ahead of kickoff and must not claim it.
+  const franchise = fakeFranchise([]);
+  const games = [game('RegularSeason', 13, 10, 20)];
+  const clock = { stage: 'NFLSeason', weekType: 'RegularSeason', weekIndex: 13 };
+  const indexTeamsByTeamIndex = new Map([[0, { externalTeamId: 10, teamIndex: 0 }]]);
+  const player = fakePlayer({ externalPlayerId: 1, teamIndex: 0 });
+
+  const rows = await extractPlayerWeekStatus(franchise, { players: [player], games, clock, indexTeamsByTeamIndex });
+  const predictive = byWeekIndex(rows, 13)[0];
+  assert.equal(predictive.status, 'active');
+});
+
+test('crosses the RegularSeason -> WildcardPlayoff boundary correctly for the retrospective row', async () => {
+  // clock says WildcardPlayoff week 18; the completed week is RegularSeason 17, NOT
+  // "WildcardPlayoff 17" (which doesn't exist) — this is the bug that was found and
+  // fixed against real save data.
+  const games = [
+    game('RegularSeason', 17, 10, 20),
+    game('WildcardPlayoff', 18, 10, 40),
+  ];
+  const player = fakePlayer({ externalPlayerId: 1, teamIndex: 0 }); // no stat chain -> inactive, that's fine here
+  const franchise = fakeFranchise([]);
+  const clock = { stage: 'NFLSeason', weekType: 'WildcardPlayoff', weekIndex: 18 };
+  const indexTeamsByTeamIndex = new Map([[0, { externalTeamId: 10, teamIndex: 0 }]]);
+
+  const rows = await extractPlayerWeekStatus(franchise, { players: [player], games, clock, indexTeamsByTeamIndex });
+  const retrospective = byWeekIndex(rows, 17)[0];
+  assert.equal(retrospective.weekType, 'RegularSeason');
+
+  const predictive = byWeekIndex(rows, 18)[0];
+  assert.equal(predictive.weekType, 'WildcardPlayoff');
+});
+
+test('returns empty during the offseason', async () => {
+  const franchise = fakeFranchise([]);
+  const clock = { stage: 'OffSeason', weekType: 'OffSeason', weekIndex: 4 };
+  const rows = await extractPlayerWeekStatus(franchise, {
+    players: [fakePlayer({ externalPlayerId: 1, teamIndex: 0 })],
+    games: [],
+    clock,
+    indexTeamsByTeamIndex: new Map(),
+  });
+  assert.deepEqual(rows, []);
+});
+
+test('classifies bye, injured, and free_agent correctly in both predictive and retrospective rows', async () => {
+  const games = [game('RegularSeason', 4, 10, 20)]; // only teams 10,20 play week 4; team 30 is on bye
+  const franchise = fakeFranchise([]);
+  const clock = { stage: 'NFLSeason', weekType: 'RegularSeason', weekIndex: 5 };
+  const indexTeamsByTeamIndex = new Map([
+    [0, { externalTeamId: 10, teamIndex: 0 }],
+    [2, { externalTeamId: 30, teamIndex: 2 }],
+  ]);
+
+  const players = [
+    fakePlayer({ externalPlayerId: 1, teamIndex: 2 }), // bye (team 30 has no game week 4)
+    fakePlayer({ externalPlayerId: 2, teamIndex: 0, injuryStatus: 'Injured' }), // injured takes priority
+    fakePlayer({ externalPlayerId: 3, teamIndex: 0, contractStatus: 'FreeAgent' }), // free_agent takes priority
+  ];
+
+  const rows = await extractPlayerWeekStatus(franchise, { players, games, clock, indexTeamsByTeamIndex });
+  const retrospective = byWeekIndex(rows, 4);
+  const byId = new Map(retrospective.map((r) => [r.externalPlayerId, r.status]));
+  assert.equal(byId.get(1), 'bye');
+  assert.equal(byId.get(2), 'injured');
+  assert.equal(byId.get(3), 'free_agent');
+
+  // injured/bye/free_agent are live fields — no reason for the predictive row (week 5,
+  // still bye/injured/FA in this test's fixed player state) to disagree with retrospective.
+  const predictive = byWeekIndex(rows, 5);
+  const predictiveById = new Map(predictive.map((r) => [r.externalPlayerId, r.status]));
+  assert.equal(predictiveById.get(1), 'bye');
+  assert.equal(predictiveById.get(2), 'injured');
+  assert.equal(predictiveById.get(3), 'free_agent');
+});
+
+test('a newly-injured player is reflected immediately in the predictive row, no lag', async () => {
+  // Mirrors the real-save finding: injury status is a live field, unlike GameStats.
+  // A player injured in the game that JUST decided this week shows up right away.
+  const games = [game('RegularSeason', 13, 10, 20)];
+  const franchise = fakeFranchise([]);
+  const clock = { stage: 'NFLSeason', weekType: 'RegularSeason', weekIndex: 13 };
+  const indexTeamsByTeamIndex = new Map([[0, { externalTeamId: 10, teamIndex: 0 }]]);
+  const player = fakePlayer({ externalPlayerId: 1, teamIndex: 0, injuryStatus: 'Injured' });
+
+  const rows = await extractPlayerWeekStatus(franchise, { players: [player], games, clock, indexTeamsByTeamIndex });
+  const predictive = byWeekIndex(rows, 13)[0];
+  assert.equal(predictive.status, 'injured');
+});

package/test/state.test.js

@@ -0,0 +1,54 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { loadState, saveState } from '../src/lib/state.js';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+function withTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'extractor-state-test-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('loadState returns null when no file exists', () => {
+  withTempDir((dir) => {
+    const state = loadState(join(dir, 'nope.json'));
+    assert.equal(state, null);
+  });
+});
+
+test('saveState then loadState round-trips the captured key set', () => {
+  withTempDir((dir) => {
+    const statePath = join(dir, 'state.json');
+    const keys = new Set(['0:RegularSeason:0:3:25', '0:RegularSeason:1:3:19']);
+
+    saveState(statePath, { capturedGameKeys: keys, toolVersion: '0.1.0', savePath: '/some/save' });
+    const loaded = loadState(statePath);
+
+    assert.deepEqual([...loaded.capturedGameKeys].sort(), [...keys].sort());
+  });
+});
+
+test('saveState creates parent directories that do not exist yet', () => {
+  withTempDir((dir) => {
+    const statePath = join(dir, 'nested', 'deeper', 'state.json');
+    saveState(statePath, { capturedGameKeys: new Set(['a']), toolVersion: '0.1.0', savePath: 'x' });
+    const loaded = loadState(statePath);
+    assert.ok(loaded.capturedGameKeys.has('a'));
+  });
+});
+
+test('saveState overwrites a previous state file (not append)', () => {
+  withTempDir((dir) => {
+    const statePath = join(dir, 'state.json');
+    saveState(statePath, { capturedGameKeys: new Set(['a']), toolVersion: '0.1.0', savePath: 'x' });
+    saveState(statePath, { capturedGameKeys: new Set(['b']), toolVersion: '0.1.0', savePath: 'x' });
+
+    const loaded = loadState(statePath);
+    assert.deepEqual([...loaded.capturedGameKeys], ['b']);
+  });
+});

package/test/team-game-stats.test.js

@@ -0,0 +1,119 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractTeamGameStats } from '../src/extract/team-game-stats.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+function buildGame({ homeScore, awayScore, homeStats, awayStats }) {
+  const teamTable = fakeTable('Team', [fakeRecord({ TeamIndex: 0 }), fakeRecord({ TeamIndex: 1 })]);
+  const statCacheTable = fakeTable('TeamStats', [fakeRecord(homeStats), fakeRecord(awayStats)]);
+
+  const seasonGameRecord = fakeRecord(
+    {},
+    {
+      HomeTeam: { tableId: teamTable._id, rowNumber: 0 },
+      AwayTeam: { tableId: teamTable._id, rowNumber: 1 },
+      HomeTeamStatCache: { tableId: statCacheTable._id, rowNumber: 0 },
+      AwayTeamStatCache: { tableId: statCacheTable._id, rowNumber: 1 },
+    },
+  );
+
+  const franchise = fakeFranchise([teamTable, statCacheTable]);
+  const indexTeamsByTeamIndex = new Map([
+    [0, { externalTeamId: 10, teamIndex: 0 }],
+    [1, { externalTeamId: 20, teamIndex: 1 }],
+  ]);
+  const game = {
+    seasonWeekType: 'RegularSeason',
+    seasonWeek: 0,
+    homeExternalTeamId: 10,
+    awayExternalTeamId: 20,
+    homeScore,
+    awayScore,
+    _record: seasonGameRecord,
+  };
+
+  return { franchise, indexTeamsByTeamIndex, game };
+}
+
+test('a shutout (0 points/0 yards allowed) still emits dst_points_allowed and dst_yards_allowed', async () => {
+  // Home team shuts the away team out: home allowed 0 points, 0 yards, and also
+  // recorded 0 sacks/takeaways this game (a plausible shutout-by-turnovers-and-D line).
+  const { franchise, indexTeamsByTeamIndex, game } = buildGame({
+    homeScore: 24,
+    awayScore: 0,
+    homeStats: { SACKS: 0, TAKEAWAYS: 0, TWOPOINTCONVMADE: 0, DEFPASSYARDS: 0, DEFRUSHYARDS: 0 },
+    awayStats: { SACKS: 1, TAKEAWAYS: 1, TWOPOINTCONVMADE: 0, DEFPASSYARDS: 150, DEFRUSHYARDS: 50 },
+  });
+
+  const rows = await extractTeamGameStats(franchise, {
+    games: [game],
+    playerGameStatsByGameAndTeam: new Map(),
+    indexTeamsByTeamIndex,
+  });
+
+  const homeRows = new Map(rows.filter((r) => r.externalTeamId === 10).map((r) => [r.statCategoryKey, r.value]));
+
+  // Linear categories at 0: skipped (scoring-identical to a missing row, per
+  // v_team_game_points — a plain SUM(value * points_per_unit)).
+  assert.equal(homeRows.has('dst_sacks'), false);
+  assert.equal(homeRows.has('dst_takeaways'), false);
+  assert.equal(homeRows.has('two_point_conversions'), false);
+  assert.equal(homeRows.has('dst_tds'), false);
+  assert.equal(homeRows.has('dst_safeties'), false);
+
+  // Tiered categories: ALWAYS present even at 0 — this is exactly the shutout case
+  // where 0 is the seed ruleset's highest-value bucket (10 pt bonus), not a no-op.
+  // Dropping these would make v_fantasy_slot_points score the shutout as 0 via its
+  // COALESCE fallback instead of the correct bonus.
+  assert.equal(homeRows.get('dst_yards_allowed'), 0);
+  assert.equal(homeRows.get('dst_points_allowed'), 0);
+});
+
+test('nonzero linear categories are emitted normally alongside the always-on tiered ones', async () => {
+  const { franchise, indexTeamsByTeamIndex, game } = buildGame({
+    homeScore: 17,
+    awayScore: 24,
+    homeStats: { SACKS: 2, TAKEAWAYS: 1, TWOPOINTCONVMADE: 1, DEFPASSYARDS: 200, DEFRUSHYARDS: 80 },
+    awayStats: { SACKS: 0, TAKEAWAYS: 0, TWOPOINTCONVMADE: 0, DEFPASSYARDS: 0, DEFRUSHYARDS: 0 },
+  });
+
+  const rows = await extractTeamGameStats(franchise, {
+    games: [game],
+    playerGameStatsByGameAndTeam: new Map(),
+    indexTeamsByTeamIndex,
+  });
+
+  const homeRows = new Map(rows.filter((r) => r.externalTeamId === 10).map((r) => [r.statCategoryKey, r.value]));
+  assert.equal(homeRows.get('dst_sacks'), 2);
+  assert.equal(homeRows.get('dst_takeaways'), 1);
+  assert.equal(homeRows.get('two_point_conversions'), 1);
+  assert.equal(homeRows.get('dst_yards_allowed'), 280);
+  assert.equal(homeRows.get('dst_points_allowed'), 24);
+});
+
+test('dst_tds / dst_safeties are summed from player stats and zero-skipped like other linear categories', async () => {
+  const { franchise, indexTeamsByTeamIndex, game } = buildGame({
+    homeScore: 10,
+    awayScore: 7,
+    homeStats: { SACKS: 0, TAKEAWAYS: 0, TWOPOINTCONVMADE: 0, DEFPASSYARDS: 100, DEFRUSHYARDS: 50 },
+    awayStats: { SACKS: 0, TAKEAWAYS: 0, TWOPOINTCONVMADE: 0, DEFPASSYARDS: 100, DEFRUSHYARDS: 50 },
+  });
+
+  const playerGameStatsByGameAndTeam = new Map([
+    ['RegularSeason:0:10:20:10', [{ statCategoryKey: 'def_int_tds', value: 1 }, { statCategoryKey: 'def_safeties', value: 1 }]],
+  ]);
+
+  const rows = await extractTeamGameStats(franchise, {
+    games: [game],
+    playerGameStatsByGameAndTeam,
+    indexTeamsByTeamIndex,
+  });
+
+  const homeRows = new Map(rows.filter((r) => r.externalTeamId === 10).map((r) => [r.statCategoryKey, r.value]));
+  const awayRows = new Map(rows.filter((r) => r.externalTeamId === 20).map((r) => [r.statCategoryKey, r.value]));
+
+  assert.equal(homeRows.get('dst_tds'), 1);
+  assert.equal(homeRows.get('dst_safeties'), 1);
+  assert.equal(awayRows.has('dst_tds'), false, 'away team had no defensive TDs this game — skipped');
+  assert.equal(awayRows.has('dst_safeties'), false);
+});