@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/src/game-definition/__tests__/zone-operations.test.ts

@@ -0,0 +1,362 @@
+import { describe, expect, it } from "bun:test";
+import { createCardId, createPlayerId } from "@drmxrcy/tcg-core";
+import {
+  addCardToZone,
+  createZoneState,
+  getCardsInZone,
+  isCardInZone,
+  moveCardBetweenZones,
+  removeCardFromZone,
+  type ZoneState,
+} from "../zone-operations";
+
+/**
+ * Task 1.5, 1.6: Tests for Zone Transition Operations
+ *
+ * Validates helper functions for managing cards in zones:
+ * - Adding cards to zones
+ * - Removing cards from zones
+ * - Moving cards between zones
+ * - Querying cards in zones
+ *
+ * References:
+ * - Rule 8.1 (Zones are separate)
+ * - Rule 8.4.4 (Leaving play triggers abilities)
+ * - Rule 8.1.5 (Cards entering private zones lose all info)
+ */
+
+// Test helper to create test players
+function createTestPlayers(...names: string[]) {
+  return names.map((name) => createPlayerId(name));
+}
+
+// Test helper to create test cards
+function createTestCards(...names: string[]) {
+  return names.map((name) => createCardId(name));
+}
+
+describe("Zone Operations", () => {
+  describe("createZoneState", () => {
+    it("should create empty zone state for all players", () => {
+      const [player1, player2] = createTestPlayers("player1", "player2");
+
+      const zoneState = createZoneState([player1, player2]);
+
+      expect(zoneState[player1]).toEqual([]);
+      expect(zoneState[player2]).toEqual([]);
+    });
+  });
+
+  describe("addCardToZone", () => {
+    it("should add card to player's zone", () => {
+      const [player1, player2] = createTestPlayers("player1", "player2");
+      const [card1] = createTestCards("card-1");
+
+      const zoneState: ZoneState = {
+        [player1]: [],
+        [player2]: [],
+      };
+
+      addCardToZone(zoneState, player1, card1);
+
+      expect(zoneState[player1]).toEqual([card1]);
+      expect(zoneState[player2]).toEqual([]);
+    });
+
+    it("should add multiple cards maintaining order", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1, card2, card3] = createTestCards(
+        "card-1",
+        "card-2",
+        "card-3",
+      );
+
+      const zoneState: ZoneState = {
+        [player1]: [],
+      };
+
+      addCardToZone(zoneState, player1, card1);
+      addCardToZone(zoneState, player1, card2);
+      addCardToZone(zoneState, player1, card3);
+
+      expect(zoneState[player1]).toEqual([card1, card2, card3]);
+    });
+  });
+
+  describe("removeCardFromZone", () => {
+    it("should remove card from player's zone", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1, card2] = createTestCards("card-1", "card-2");
+
+      const zoneState: ZoneState = {
+        [player1]: [card1, card2],
+      };
+
+      removeCardFromZone(zoneState, player1, card1);
+
+      expect(zoneState[player1]).toEqual([card2]);
+    });
+
+    it("should maintain order when removing from middle", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1, card2, card3] = createTestCards(
+        "card-1",
+        "card-2",
+        "card-3",
+      );
+
+      const zoneState: ZoneState = {
+        [player1]: [card1, card2, card3],
+      };
+
+      removeCardFromZone(zoneState, player1, card2);
+
+      expect(zoneState[player1]).toEqual([card1, card3]);
+    });
+
+    it("should do nothing if card not in zone", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1, card2] = createTestCards("card-1", "card-2");
+
+      const zoneState: ZoneState = {
+        [player1]: [card1],
+      };
+
+      removeCardFromZone(zoneState, player1, card2);
+
+      expect(zoneState[player1]).toEqual([card1]);
+    });
+  });
+
+  describe("moveCardBetweenZones", () => {
+    it("should move card from one zone to another", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1] = createTestCards("card-1");
+
+      const handZone: ZoneState = {
+        [player1]: [card1],
+      };
+
+      const playZone: ZoneState = {
+        [player1]: [],
+      };
+
+      moveCardBetweenZones(handZone, playZone, player1, card1);
+
+      expect(handZone[player1]).toEqual([]);
+      expect(playZone[player1]).toEqual([card1]);
+    });
+
+    it("should handle moving between zones of different players", () => {
+      const [player1, player2] = createTestPlayers("player1", "player2");
+      const [card1] = createTestCards("card-1");
+
+      const player1Hand: ZoneState = {
+        [player1]: [card1],
+      };
+
+      const player2Hand: ZoneState = {
+        [player2]: [],
+      };
+
+      // This would be unusual but tests the operation works
+      removeCardFromZone(player1Hand, player1, card1);
+      addCardToZone(player2Hand, player2, card1);
+
+      expect(player1Hand[player1]).toEqual([]);
+      expect(player2Hand[player2]).toEqual([card1]);
+    });
+
+    it("should maintain card order in destination zone", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1, card2, card3] = createTestCards(
+        "card-1",
+        "card-2",
+        "card-3",
+      );
+
+      const sourceZone: ZoneState = {
+        [player1]: [card2],
+      };
+
+      const destZone: ZoneState = {
+        [player1]: [card1, card3],
+      };
+
+      moveCardBetweenZones(sourceZone, destZone, player1, card2);
+
+      expect(sourceZone[player1]).toEqual([]);
+      expect(destZone[player1]).toEqual([card1, card3, card2]);
+    });
+  });
+
+  describe("isCardInZone", () => {
+    it("should return true if card is in player's zone", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1] = createTestCards("card-1");
+
+      const zoneState: ZoneState = {
+        [player1]: [card1],
+      };
+
+      expect(isCardInZone(zoneState, player1, card1)).toBe(true);
+    });
+
+    it("should return false if card is not in player's zone", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1, card2] = createTestCards("card-1", "card-2");
+
+      const zoneState: ZoneState = {
+        [player1]: [card1],
+      };
+
+      expect(isCardInZone(zoneState, player1, card2)).toBe(false);
+    });
+
+    it("should return false if player has no zone", () => {
+      const [player1, player2] = createTestPlayers("player1", "player2");
+      const [card1] = createTestCards("card-1");
+
+      const zoneState: ZoneState = {
+        [player1]: [card1],
+      };
+
+      expect(isCardInZone(zoneState, player2, card1)).toBe(false);
+    });
+  });
+
+  describe("getCardsInZone", () => {
+    it("should return all cards in player's zone", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1, card2, card3] = createTestCards(
+        "card-1",
+        "card-2",
+        "card-3",
+      );
+
+      const zoneState: ZoneState = {
+        [player1]: [card1, card2, card3],
+      };
+
+      const cards = getCardsInZone(zoneState, player1);
+
+      expect(cards).toEqual([card1, card2, card3]);
+    });
+
+    it("should return empty array if player has no cards", () => {
+      const [player1] = createTestPlayers("player1");
+
+      const zoneState: ZoneState = {
+        [player1]: [],
+      };
+
+      const cards = getCardsInZone(zoneState, player1);
+
+      expect(cards).toEqual([]);
+    });
+
+    it("should return empty array if player has no zone", () => {
+      const [player1] = createTestPlayers("player1");
+
+      const zoneState: ZoneState = {};
+
+      const cards = getCardsInZone(zoneState, player1);
+
+      expect(cards).toEqual([]);
+    });
+
+    it("should return copy of array (not mutate original)", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card1] = createTestCards("card-1");
+
+      const zoneState: ZoneState = {
+        [player1]: [card1],
+      };
+
+      const cards = getCardsInZone(zoneState, player1);
+      cards.push(createCardId("card-2"));
+
+      // Original should be unchanged
+      expect(zoneState[player1]).toEqual([card1]);
+    });
+  });
+
+  describe("Zone Transition Scenarios", () => {
+    it("should handle draw card scenario (deck -> hand)", () => {
+      const [player1] = createTestPlayers("player1");
+      const [topCard, card2, card3] = createTestCards(
+        "top-card",
+        "card-2",
+        "card-3",
+      );
+
+      const deckZone: ZoneState = {
+        [player1]: [topCard, card2, card3],
+      };
+
+      const handZone: ZoneState = {
+        [player1]: [],
+      };
+
+      // Draw top card
+      moveCardBetweenZones(deckZone, handZone, player1, topCard);
+
+      expect(deckZone[player1]).toHaveLength(2);
+      expect(handZone[player1]).toEqual([topCard]);
+    });
+
+    it("should handle play card scenario (hand -> play)", () => {
+      const [player1] = createTestPlayers("player1");
+      const [card] = createTestCards("character-1");
+
+      const handZone: ZoneState = {
+        [player1]: [card],
+      };
+
+      const playZone: ZoneState = {
+        [player1]: [],
+      };
+
+      moveCardBetweenZones(handZone, playZone, player1, card);
+
+      expect(handZone[player1]).toEqual([]);
+      expect(playZone[player1]).toEqual([card]);
+    });
+
+    it("should handle banish scenario (play -> discard)", () => {
+      const [player1] = createTestPlayers("player1");
+      const [character] = createTestCards("character-1");
+
+      const playZone: ZoneState = {
+        [player1]: [character],
+      };
+
+      const discardZone: ZoneState = {
+        [player1]: [],
+      };
+
+      moveCardBetweenZones(playZone, discardZone, player1, character);
+
+      expect(playZone[player1]).toEqual([]);
+      expect(discardZone[player1]).toEqual([character]);
+    });
+
+    it("should handle ink card scenario (hand -> inkwell)", () => {
+      const [player1] = createTestPlayers("player1");
+      const [inkableCard] = createTestCards("inkable-1");
+
+      const handZone: ZoneState = {
+        [player1]: [inkableCard],
+      };
+
+      const inkwellZone: ZoneState = {
+        [player1]: [],
+      };
+
+      moveCardBetweenZones(handZone, inkwellZone, player1, inkableCard);
+
+      expect(handZone[player1]).toEqual([]);
+      expect(inkwellZone[player1]).toEqual([inkableCard]);
+    });
+  });
+});

package/src/game-definition/__tests__/zones.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from "bun:test";
+import { type LorcanaZoneId, lorcanaZones } from "../zones";
+
+/**
+ * Task 1.3: Tests for Zone Configurations
+ *
+ * Validates zone configurations match Lorcana Comprehensive Rules Section 8:
+ * - Deck (Rule 8.2): Private, ordered, facedown
+ * - Hand (Rule 8.3): Private, can rearrange
+ * - Play (Rule 8.4): Public, all can see
+ * - Discard (Rule 8.6): Public, ordered, faceup
+ * - Inkwell (Rule 8.5): Private, facedown
+ *
+ * References:
+ * - Rule 8.1.2 (Public zones)
+ * - Rule 8.1.3 (Private zones)
+ * - Rule 8.2.2 (Deck is private and ordered)
+ * - Rule 8.3.2 (Hand is private)
+ * - Rule 8.4.3 (Play is public)
+ * - Rule 8.5.3 (Inkwell is private)
+ * - Rule 8.6.3 (Discard is public and ordered)
+ */
+
+describe("Lorcana Zone Configurations", () => {
+  it("should have all 6 required zones", () => {
+    const zoneIds = Object.keys(lorcanaZones);
+
+    expect(zoneIds).toContain("deck");
+    expect(zoneIds).toContain("hand");
+    expect(zoneIds).toContain("play");
+    expect(zoneIds).toContain("discard");
+    expect(zoneIds).toContain("inkwell");
+    expect(zoneIds).toContain("limbo");
+    expect(zoneIds).toHaveLength(6);
+  });
+
+  describe("Deck Zone", () => {
+    it("should be private visibility (Rule 8.2.2)", () => {
+      expect(lorcanaZones.deck.visibility).toBe("owner");
+    });
+
+    it("should be ordered (Rule 8.2.2)", () => {
+      expect(lorcanaZones.deck.ordered).toBe(true);
+    });
+
+    it("should be facedown (Rule 8.2.2)", () => {
+      expect(lorcanaZones.deck.facedown).toBe(true);
+    });
+  });
+
+  describe("Hand Zone", () => {
+    it("should be private visibility (Rule 8.3.2)", () => {
+      expect(lorcanaZones.hand.visibility).toBe("owner");
+    });
+
+    it("should be unordered - can rearrange (Rule 8.3.2)", () => {
+      expect(lorcanaZones.hand.ordered).toBe(false);
+    });
+
+    it("should not be facedown (cards are visible to owner)", () => {
+      expect(lorcanaZones.hand.facedown).toBe(false);
+    });
+  });
+
+  describe("Play Zone", () => {
+    it("should be public visibility (Rule 8.4.3)", () => {
+      expect(lorcanaZones.play.visibility).toBe("all");
+    });
+
+    it("should be unordered (no specific arrangement required)", () => {
+      expect(lorcanaZones.play.ordered).toBe(false);
+    });
+
+    it("should not be facedown (cards are visible)", () => {
+      expect(lorcanaZones.play.facedown).toBe(false);
+    });
+  });
+
+  describe("Discard Zone", () => {
+    it("should be public visibility (Rule 8.6.3)", () => {
+      expect(lorcanaZones.discard.visibility).toBe("all");
+    });
+
+    it("should be ordered (Rule 8.6.3)", () => {
+      expect(lorcanaZones.discard.ordered).toBe(true);
+    });
+
+    it("should not be facedown (cards are visible)", () => {
+      expect(lorcanaZones.discard.facedown).toBe(false);
+    });
+  });
+
+  describe("Inkwell Zone", () => {
+    it("should be private visibility (Rule 8.5.3)", () => {
+      expect(lorcanaZones.inkwell.visibility).toBe("owner");
+    });
+
+    it("should be unordered (can arrange as convenient) (Rule 8.5.4)", () => {
+      expect(lorcanaZones.inkwell.ordered).toBe(false);
+    });
+
+    it("should be facedown (Rule 8.5.2, 8.5.3)", () => {
+      expect(lorcanaZones.inkwell.facedown).toBe(true);
+    });
+  });
+
+  describe("Limbo Zone", () => {
+    it("should be private visibility (phased out cards not directly interactable)", () => {
+      expect(lorcanaZones.limbo.visibility).toBe("owner");
+    });
+
+    it("should be ordered (maintain stacking sequence for shifts)", () => {
+      expect(lorcanaZones.limbo.ordered).toBe(true);
+    });
+
+    it("should not be facedown (for tracking purposes)", () => {
+      expect(lorcanaZones.limbo.facedown).toBe(false);
+    });
+  });
+
+  describe("Zone Properties Validation", () => {
+    it("should have exactly 4 private zones", () => {
+      const privateZones = Object.values(lorcanaZones).filter(
+        (zone) => zone.visibility === "owner",
+      );
+      expect(privateZones).toHaveLength(4); // deck, hand, inkwell, limbo
+    });
+
+    it("should have exactly 2 public zones", () => {
+      const publicZones = Object.values(lorcanaZones).filter(
+        (zone) => zone.visibility === "all",
+      );
+      expect(publicZones).toHaveLength(2); // play, discard
+    });
+
+    it("should have exactly 2 facedown zones", () => {
+      const facedownZones = Object.values(lorcanaZones).filter(
+        (zone) => zone.facedown === true,
+      );
+      expect(facedownZones).toHaveLength(2); // deck, inkwell
+    });
+
+    it("should have exactly 3 ordered zones", () => {
+      const orderedZones = Object.values(lorcanaZones).filter(
+        (zone) => zone.ordered === true,
+      );
+      expect(orderedZones).toHaveLength(3); // deck, discard, limbo
+    });
+  });
+
+  describe("Zone Type Safety", () => {
+    it("should type-check valid zone IDs", () => {
+      const validIds: LorcanaZoneId[] = [
+        "deck",
+        "hand",
+        "play",
+        "discard",
+        "inkwell",
+        "limbo",
+      ];
+
+      for (const id of validIds) {
+        expect(lorcanaZones[id]).toBeDefined();
+      }
+    });
+
+    it("should have correct zone ID type", () => {
+      // This test validates TypeScript type checking at compile time
+      const zoneId: LorcanaZoneId = "deck";
+      expect(zoneId).toBe("deck");
+
+      // TypeScript should prevent this:
+      // const invalid: LorcanaZoneId = "invalid"; // Type error
+    });
+  });
+});

package/src/game-definition/definition.ts

@@ -0,0 +1,45 @@
+import type { GameDefinition } from "@drmxrcy/tcg-core";
+import type {
+  LorcanaCardMeta,
+  LorcanaGameState,
+  LorcanaMoveParams,
+} from "../types";
+import { lorcanaFlow } from "./flow/turn-flow";
+import { lorcanaMoves } from "./moves";
+import { setupLorcanaGame } from "./setup/game-setup";
+import { trackerConfig } from "./trackers/tracker-config";
+import { checkLoreVictory } from "./win-conditions/lore-victory";
+// Import modular components
+import { lorcanaZones } from "./zones/zone-configs";
+
+/**
+ * Complete Lorcana Game Definition
+ *
+ * Modular architecture with single responsibility:
+ * - zones/: Zone configurations
+ * - flow/: Turn and phase flow
+ * - moves/: All game moves organized by category
+ * - trackers/: Action tracking configuration
+ * - setup/: Game initialization
+ * - win-conditions/: Victory conditions
+ *
+ * Benefits:
+ * - Easy to navigate and maintain
+ * - Test components in isolation
+ * - Clear separation of concerns
+ * - Scalable for future additions
+ */
+export const lorcanaGameDefinition: GameDefinition<
+  LorcanaGameState,
+  LorcanaMoveParams,
+  unknown, // Card definitions (to be added)
+  LorcanaCardMeta
+> = {
+  name: "Disney Lorcana TCG",
+  zones: lorcanaZones,
+  flow: lorcanaFlow,
+  moves: lorcanaMoves,
+  trackers: trackerConfig,
+  setup: setupLorcanaGame,
+  endIf: checkLoreVictory,
+};