madden-fantasy-extractor 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "madden-fantasy-extractor",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Reads a Madden franchise save and produces a signed stat_import JSON payload for ingest.",
   "type": "module",
   "main": "src/index.js",

package/src/extract/payload.js

@@ -11,7 +11,7 @@
 // week, independent of which games' stats have already been captured).
 
 import { extractClock } from './clock.js';
-import { extractTeams, indexTeamsByTeamIndex } from './teams.js';
+import { extractTeams, extractDivisionConferenceByTeam, indexTeamsByTeamIndex } from './teams.js';
 import { extractPlayers, indexPlayersByTeamAndJersey } from './players.js';
 import { extractGames, gameKey } from './games.js';
 import { extractPlayerGameStats } from './player-game-stats.js';
@@ -24,11 +24,17 @@ import { extractFranchiseNews } from './franchise-news.js';
 import { extractLeagueAwards } from './league-awards.js';
 import { selectGamesToCapture, selectReadyGames, selectPendingGames, unionCapturedKeys } from '../lib/incremental.js';
 
-const PAYLOAD_SCHEMA_VERSION = '1.2.0';
+const PAYLOAD_SCHEMA_VERSION = '1.4.0';
 
 export async function buildPayload(franchise, { toolVersion, fullMode = false, capturedGameKeys = new Set() }) {
   const clock = await extractClock(franchise);
   const teams = await extractTeams(franchise);
+  const divisionConferenceByTeam = await extractDivisionConferenceByTeam(franchise);
+  for (const team of teams) {
+    const dc = divisionConferenceByTeam.get(team.externalTeamId);
+    team.divisionName = dc?.divisionName ?? null;
+    team.conferenceName = dc?.conferenceName ?? null;
+  }
   const teamIdx = indexTeamsByTeamIndex(teams);
 
   const allGames = await extractGames(franchise, { indexTeamsByTeamIndex: teamIdx });

package/src/extract/teams.js

@@ -4,7 +4,7 @@
 // the real 32 teams live in the capacity-37 instance, filtered to TEAM_TYPE='Current'.
 // TeamIndex 32 is not a team, it's the FA/practice pool; we never create a row for it.
 
-import { getTableByNameAndCapacity, liveRecords } from '../lib/franchise-table.js';
+import { getTableByNameAndCapacity, getAllLiveRecordsAcrossInstances, liveRecords, resolveFieldRef, resolveWrapperSlots } from '../lib/franchise-table.js';
 
 export async function extractTeams(franchise) {
   const table = await getTableByNameAndCapacity(franchise, 'Team');
@@ -35,6 +35,37 @@ export async function extractTeams(franchise) {
   }));
 }
 
+/**
+ * Division/conference membership is NOT a field on Team -- it's the reverse
+ * relationship (Conference -> Divisions -> Teams), confirmed via real-save
+ * investigation (see docs/superpowers/specs/2026-07-26-conference-division-standings-
+ * design.md in the madden-fantasy repo). Conference itself exists as TWO SEPARATE
+ * table instances in the save (one AFC, one NFC), which is why this reads via
+ * getAllLiveRecordsAcrossInstances rather than getTableByNameAndCapacity -- the
+ * latter would silently return only one conference.
+ *
+ * Returns a lookup from externalTeamId (Team.PresentationId) to
+ * { divisionName, conferenceName }.
+ */
+export async function extractDivisionConferenceByTeam(franchise) {
+  const conferences = await getAllLiveRecordsAcrossInstances(franchise, 'Conference');
+  const result = new Map();
+  for (const conf of conferences) {
+    const divWrapper = await resolveFieldRef(franchise, conf, 'Divisions');
+    if (!divWrapper) continue;
+    const divisions = await resolveWrapperSlots(franchise, divWrapper, 'Division');
+    for (const div of divisions) {
+      const teamWrapper = await resolveFieldRef(franchise, div, 'Teams');
+      if (!teamWrapper) continue;
+      const teams = await resolveWrapperSlots(franchise, teamWrapper, 'Team');
+      for (const team of teams) {
+        result.set(team.PresentationId, { divisionName: div.Name, conferenceName: conf.Name });
+      }
+    }
+  }
+  return result;
+}
+
 /** TeamIndex (0..31) -> extracted team row, for resolving Player.TeamIndex and SeasonGame refs. */
 export function indexTeamsByTeamIndex(teams) {
   return new Map(teams.map((t) => [t.teamIndex, t]));

package/src/lib/franchise-table.js

@@ -29,6 +29,25 @@ export async function getTableByNameAndCapacity(franchise, name, opts) {
   return table;
 }
 
+/**
+ * Some tables exist as multiple real (non-decoy) instances rather than one real
+ * instance plus decoys -- confirmed for `Conference` (two capacity-1 instances, one
+ * holding AFC, one holding NFC; see docs/superpowers/specs/2026-07-26-conference-
+ * division-standings-design.md in the madden-fantasy repo). Unlike
+ * getTableByNameAndCapacity, this reads and returns every instance's live records
+ * merged into one array, rather than picking a single "best" instance.
+ */
+export async function getAllLiveRecordsAcrossInstances(franchise, name) {
+  const matches = franchise.tables.filter((t) => t.name === name);
+  if (matches.length === 0) throw new Error(`No table named "${name}" in this save`);
+  const allRecords = [];
+  for (const table of matches) {
+    await table.readRecords();
+    allRecords.push(...liveRecords(table));
+  }
+  return allRecords;
+}
+
 /**
  * Resolve a reference field to its target record, reading the target table first if needed.
  *

package/test/franchise-table.test.js

@@ -0,0 +1,37 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { getAllLiveRecordsAcrossInstances } from '../src/lib/franchise-table.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+test('getAllLiveRecordsAcrossInstances: merges live records across multiple instances of the same table name', async () => {
+  const afcRecord = fakeRecord({ Name: 'AFC' });
+  const afcTable = fakeTable('Conference', [afcRecord]);
+  const nfcRecord = fakeRecord({ Name: 'NFC' });
+  const nfcTable = fakeTable('Conference', [nfcRecord]);
+
+  const franchise = fakeFranchise([afcTable, nfcTable]);
+
+  const records = await getAllLiveRecordsAcrossInstances(franchise, 'Conference');
+  assert.equal(records.length, 2);
+  assert.deepEqual(records.map((r) => r.Name).sort(), ['AFC', 'NFC']);
+});
+
+test('getAllLiveRecordsAcrossInstances: skips empty records within each instance', async () => {
+  const liveRecord = fakeRecord({ Name: 'AFC' });
+  const emptyRecord = { ...fakeRecord({}), isEmpty: true };
+  const table = fakeTable('Conference', [liveRecord, emptyRecord]);
+
+  const franchise = fakeFranchise([table]);
+
+  const records = await getAllLiveRecordsAcrossInstances(franchise, 'Conference');
+  assert.equal(records.length, 1);
+  assert.equal(records[0].Name, 'AFC');
+});
+
+test('getAllLiveRecordsAcrossInstances: throws when no table with that name exists', async () => {
+  const franchise = fakeFranchise([]);
+  await assert.rejects(
+    () => getAllLiveRecordsAcrossInstances(franchise, 'Conference'),
+    /No table named "Conference"/,
+  );
+});

package/test/teams.test.js

@@ -0,0 +1,79 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractTeams, extractDivisionConferenceByTeam } from '../src/extract/teams.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+// Builds a minimal two-conference, one-division-each save fragment: AFC -> AFC East -> 2 teams,
+// NFC -> NFC West -> 1 team. Enough to prove the two-instance Conference walk without needing
+// all 8 real divisions.
+function buildDivisionConferenceFixture() {
+  const dolphins = fakeRecord({ PresentationId: 12, DisplayName: 'Dolphins' });
+  const bills = fakeRecord({ PresentationId: 3, DisplayName: 'Bills' });
+  const teamTable = fakeTable('Team', [dolphins, bills]);
+
+  const afcEastTeamsWrapper = fakeRecord({}, {
+    Team0: { tableId: teamTable._id, rowNumber: 0 },
+    Team1: { tableId: teamTable._id, rowNumber: 1 },
+  });
+  const afcEastTeamsWrapperTable = fakeTable('DivisionTeamsWrapper', [afcEastTeamsWrapper]);
+  const afcEast = fakeRecord({ Name: 'AFC East' }, { Teams: { tableId: afcEastTeamsWrapperTable._id, rowNumber: 0 } });
+  const afcDivisionTable = fakeTable('Division', [afcEast]);
+
+  const afcDivisionsWrapper = fakeRecord({}, { Division0: { tableId: afcDivisionTable._id, rowNumber: 0 } });
+  const afcDivisionsWrapperTable = fakeTable('ConferenceDivisionsWrapper', [afcDivisionsWrapper]);
+  const afc = fakeRecord({ Name: 'AFC' }, { Divisions: { tableId: afcDivisionsWrapperTable._id, rowNumber: 0 } });
+  const afcConferenceTable = fakeTable('Conference', [afc]);
+
+  const rams = fakeRecord({ PresentationId: 20, DisplayName: 'Rams' });
+  const nfcTeamTable = fakeTable('Team', [rams]);
+  const nfcWestTeamsWrapper = fakeRecord({}, { Team0: { tableId: nfcTeamTable._id, rowNumber: 0 } });
+  const nfcWestTeamsWrapperTable = fakeTable('DivisionTeamsWrapper', [nfcWestTeamsWrapper]);
+  const nfcWest = fakeRecord({ Name: 'NFC West' }, { Teams: { tableId: nfcWestTeamsWrapperTable._id, rowNumber: 0 } });
+  const nfcDivisionTable = fakeTable('Division', [nfcWest]);
+
+  const nfcDivisionsWrapper = fakeRecord({}, { Division0: { tableId: nfcDivisionTable._id, rowNumber: 0 } });
+  const nfcDivisionsWrapperTable = fakeTable('ConferenceDivisionsWrapper', [nfcDivisionsWrapper]);
+  const nfc = fakeRecord({ Name: 'NFC' }, { Divisions: { tableId: nfcDivisionsWrapperTable._id, rowNumber: 0 } });
+  const nfcConferenceTable = fakeTable('Conference', [nfc]); // SEPARATE Conference table instance
+
+  return fakeFranchise([
+    teamTable, afcEastTeamsWrapperTable, afcDivisionTable, afcDivisionsWrapperTable, afcConferenceTable,
+    nfcTeamTable, nfcWestTeamsWrapperTable, nfcDivisionTable, nfcDivisionsWrapperTable, nfcConferenceTable,
+  ]);
+}
+
+test('extractDivisionConferenceByTeam: walks BOTH Conference table instances and merges results', async () => {
+  const franchise = buildDivisionConferenceFixture();
+  const result = await extractDivisionConferenceByTeam(franchise);
+
+  assert.equal(result.size, 3);
+  assert.deepEqual(result.get(12), { divisionName: 'AFC East', conferenceName: 'AFC' });
+  assert.deepEqual(result.get(3), { divisionName: 'AFC East', conferenceName: 'AFC' });
+  assert.deepEqual(result.get(20), { divisionName: 'NFC West', conferenceName: 'NFC' });
+});
+
+test('extractDivisionConferenceByTeam: a team not present in any division is simply absent from the map', async () => {
+  const franchise = buildDivisionConferenceFixture();
+  const result = await extractDivisionConferenceByTeam(franchise);
+  assert.equal(result.has(999), false);
+});
+
+test('extractTeams output can be merged with extractDivisionConferenceByTeam by externalTeamId', async () => {
+  // This proves the shape buildPayload's merge step (Step 12) relies on: extractTeams
+  // rows keyed by externalTeamId match extractDivisionConferenceByTeam's map keys.
+  const team = fakeRecord({
+    PresentationId: 12, TeamIndex: 0, TEAM_TYPE: 'Current',
+    DisplayName: 'Dolphins', NickName: 'Fins', ShortName: 'MIA',
+    HomeWin: 3, RoadWin: 2, HomeLoss: 1, RoadLoss: 1, HomeTie: 0, RoadTie: 0,
+    CurSeasonDivStanding: 1, CurSeasonConfStanding: 3, CurSeasonLeagStanding: 5,
+  });
+  const teamTable = fakeTable('Team', [team]);
+  const franchise = fakeFranchise([teamTable]);
+
+  const teams = await extractTeams(franchise);
+  assert.equal(teams.length, 1);
+  assert.equal(teams[0].externalTeamId, 12);
+  // divisionName/conferenceName are NOT set by extractTeams itself -- confirms the
+  // merge happens one level up, in buildPayload (Step 12), not inside this function.
+  assert.equal('divisionName' in teams[0], false);
+});