@drmxrcy/tcg-core 0.0.0-202602060542

package/src/game-definition/__tests__/move-definitions.test.ts

@@ -0,0 +1,328 @@
+import { describe, expect, it } from "bun:test";
+import { produce } from "immer";
+import type { MoveContext } from "../../moves/move-system";
+import { createMockContext } from "../../testing/test-context-factory";
+import type {
+  GameMoveDefinition,
+  GameMoveDefinitions,
+} from "../move-definitions";
+
+/**
+ * Test suite for GameMoveDefinitions type system
+ *
+ * Task 10.5, 10.6: Write tests for moves mapping
+ *
+ * Validates:
+ * - GameMoveDefinition structure
+ * - GameMoveDefinitions exhaustive mapping
+ * - Type safety for move reducers
+ * - Conditional move execution
+ */
+
+type CounterState = {
+  count: number;
+  player: string;
+  locked: boolean;
+};
+
+type CounterMoves = {
+  increment: { amount: number };
+  decrement: { amount: number };
+  reset: Record<string, never>;
+  setPlayer: { playerId: string };
+};
+
+describe("GameMoveDefinitions - Type System", () => {
+  describe("GameMoveDefinition structure", () => {
+    it("should create a valid GameMoveDefinition with reducer only", () => {
+      const incrementMove: GameMoveDefinition<CounterState> = {
+        reducer: (draft, context) => {
+          const amount = (context.params?.amount as number) || 1;
+          draft.count += amount;
+        },
+      };
+
+      expect(incrementMove.reducer).toBeFunction();
+      expect(incrementMove.condition).toBeUndefined();
+    });
+
+    it("should create a GameMoveDefinition with condition and reducer", () => {
+      const incrementMove: GameMoveDefinition<CounterState> = {
+        condition: (state) => !state.locked,
+        reducer: (draft, context) => {
+          const amount = (context.params?.amount as number) || 1;
+          draft.count += amount;
+        },
+      };
+
+      expect(incrementMove.condition).toBeFunction();
+      expect(incrementMove.reducer).toBeFunction();
+    });
+  });
+
+  describe("GameMoveDefinitions exhaustive mapping", () => {
+    it("should map all moves in TMoves type", () => {
+      const moves: GameMoveDefinitions<CounterState, CounterMoves> = {
+        increment: {
+          reducer: (draft, context) => {
+            const amount = (context.params?.amount as number) || 1;
+            draft.count += amount;
+          },
+        },
+        decrement: {
+          reducer: (draft, context) => {
+            const amount = (context.params?.amount as number) || 1;
+            draft.count -= amount;
+          },
+        },
+        reset: {
+          reducer: (draft) => {
+            draft.count = 0;
+          },
+        },
+        setPlayer: {
+          reducer: (draft, context) => {
+            draft.player = (context.params?.playerId as string) || "";
+          },
+        },
+      };
+
+      expect(Object.keys(moves)).toEqual([
+        "increment",
+        "decrement",
+        "reset",
+        "setPlayer",
+      ]);
+    });
+
+    it("should enforce that all move names have definitions", () => {
+      // TypeScript will error if any move is missing
+      const moves: GameMoveDefinitions<CounterState, CounterMoves> = {
+        increment: {
+          reducer: (draft) => {
+            draft.count += 1;
+          },
+        },
+        decrement: {
+          reducer: (draft) => {
+            draft.count -= 1;
+          },
+        },
+        reset: {
+          reducer: (draft) => {
+            draft.count = 0;
+          },
+        },
+        setPlayer: {
+          reducer: (draft) => {
+            draft.player = "test";
+          },
+        },
+      };
+
+      // All moves should be present
+      expect(moves.increment).toBeDefined();
+      expect(moves.decrement).toBeDefined();
+      expect(moves.reset).toBeDefined();
+      expect(moves.setPlayer).toBeDefined();
+    });
+  });
+
+  describe("move reducer execution", () => {
+    it("should execute reducer with Immer draft", () => {
+      const incrementMove: GameMoveDefinition<CounterState> = {
+        reducer: (draft, context) => {
+          const amount = (context.params?.amount as number) || 1;
+          draft.count += amount;
+        },
+      };
+
+      const initialState: CounterState = {
+        count: 5,
+        player: "p1",
+        locked: false,
+      };
+
+      const context: MoveContext = createMockContext({
+        playerId: "p1" as any,
+        params: { amount: 3 },
+      });
+
+      const newState = produce(initialState, (draft) => {
+        incrementMove.reducer(draft, context);
+      });
+
+      expect(newState.count).toBe(8);
+      expect(initialState.count).toBe(5); // Original unchanged
+    });
+
+    it("should support complex state modifications", () => {
+      const complexMove: GameMoveDefinition<CounterState> = {
+        reducer: (draft, context) => {
+          draft.count += 1;
+          draft.player = context.playerId;
+          draft.locked = true;
+        },
+      };
+
+      const initialState: CounterState = {
+        count: 0,
+        player: "",
+        locked: false,
+      };
+
+      const context: MoveContext = createMockContext({
+        playerId: "p1" as any,
+        params: {},
+      });
+
+      const newState = produce(initialState, (draft) => {
+        complexMove.reducer(draft, context);
+      });
+
+      expect(newState).toEqual({
+        count: 1,
+        player: "p1",
+        locked: true,
+      });
+    });
+  });
+
+  describe("move conditions", () => {
+    it("should evaluate condition before executing move", () => {
+      const lockedMove: GameMoveDefinition<CounterState> = {
+        condition: (state) => !state.locked,
+        reducer: (draft) => {
+          draft.count += 1;
+        },
+      };
+
+      const unlockedState: CounterState = {
+        count: 0,
+        player: "p1",
+        locked: false,
+      };
+
+      const lockedState: CounterState = {
+        count: 0,
+        player: "p1",
+        locked: true,
+      };
+
+      const context: MoveContext = createMockContext({
+        playerId: "p1" as any,
+        params: {},
+      });
+
+      // Should pass condition
+      expect(lockedMove.condition?.(unlockedState, context)).toBe(true);
+
+      // Should fail condition
+      expect(lockedMove.condition?.(lockedState, context)).toBe(false);
+    });
+
+    it("should support complex conditions", () => {
+      const conditionalMove: GameMoveDefinition<CounterState> = {
+        condition: (state, context) => {
+          return (
+            !state.locked &&
+            state.count < 10 &&
+            state.player === context.playerId
+          );
+        },
+        reducer: (draft) => {
+          draft.count += 1;
+        },
+      };
+
+      const validState: CounterState = {
+        count: 5,
+        player: "p1",
+        locked: false,
+      };
+
+      const context: MoveContext = createMockContext({
+        playerId: "p1" as any,
+        params: {},
+      });
+
+      expect(conditionalMove.condition?.(validState, context)).toBe(true);
+
+      // Wrong player
+      expect(
+        conditionalMove.condition?.(
+          validState,
+          createMockContext({
+            playerId: "p2" as any,
+            params: {},
+          }),
+        ),
+      ).toBe(false);
+
+      // Locked
+      expect(
+        conditionalMove.condition?.({ ...validState, locked: true }, context),
+      ).toBe(false);
+
+      // Count too high
+      expect(
+        conditionalMove.condition?.({ ...validState, count: 10 }, context),
+      ).toBe(false);
+    });
+  });
+
+  describe("type safety", () => {
+    it("should preserve state type through reducer", () => {
+      const typedMove: GameMoveDefinition<CounterState> = {
+        reducer: (draft) => {
+          // TypeScript should know draft is CounterState
+          draft.count += 1;
+          draft.player = "updated";
+          draft.locked = true;
+
+          // These should cause TypeScript errors:
+          // draft.nonExistent = true;
+          // draft.count = "string";
+        },
+      };
+
+      expect(typedMove.reducer).toBeFunction();
+    });
+
+    it("should preserve state type through condition", () => {
+      const typedMove: GameMoveDefinition<CounterState> = {
+        condition: (state) => {
+          // TypeScript should know state is CounterState
+          return state.count < 10 && !state.locked;
+
+          // This should cause TypeScript error:
+          // return state.nonExistent;
+        },
+        reducer: (draft) => {
+          draft.count += 1;
+        },
+      };
+
+      expect(typedMove.condition).toBeFunction();
+    });
+  });
+
+  describe("metadata support", () => {
+    it("should support optional metadata", () => {
+      const metadataMove: GameMoveDefinition<CounterState> = {
+        reducer: (draft) => {
+          draft.count += 1;
+        },
+        metadata: {
+          category: "counter",
+          tags: ["increment", "basic"],
+          priority: 1,
+        },
+      };
+
+      expect(metadataMove.metadata?.category).toBe("counter");
+      expect(metadataMove.metadata?.tags).toEqual(["increment", "basic"]);
+      expect(metadataMove.metadata?.priority).toBe(1);
+    });
+  });
+});

package/src/game-definition/game-definition.ts

@@ -0,0 +1,261 @@
+import type { FlowDefinition } from "../flow";
+import type { TelemetryHooks } from "../telemetry";
+import type { CardZoneConfig } from "../zones";
+import type { GameMoveDefinitions } from "./move-definitions";
+
+/**
+ * Player information for game setup
+ */
+export type Player = {
+  /** Unique player identifier */
+  id: string;
+  /** Optional player name for display */
+  name?: string;
+};
+
+/**
+ * Game end result
+ *
+ * Returned by endIf when the game has ended.
+ */
+export type GameEndResult = {
+  /** Winner identifier (player ID or special value like 'draw') */
+  winner: string;
+  /** Reason for game end (for display/logging) */
+  reason: string;
+  /** Additional metadata about the game end */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * GameDefinition Type System
+ *
+ * Task 10.2: Implement GameDefinition<TState, TMoves> type
+ *
+ * The core declarative game definition with full type safety.
+ * Generic over:
+ * - TState: Game state shape (game-specific logic state)
+ * - TMoves: Available moves (record of move names to move arg types)
+ * - TCardDefinition: Static card definition type
+ * - TCardMeta: Dynamic card metadata type
+ *
+ * @example
+ * ```typescript
+ * type MyGameState = {
+ *   players: Player[];
+ *   currentPlayer: number;
+ * };
+ *
+ * type MyMoves = {
+ *   playCard: { cardId: string };
+ *   pass: {};
+ * };
+ *
+ * type MyCardDef = {
+ *   id: string;
+ *   name: string;
+ *   cost: number;
+ * };
+ *
+ * type MyCardMeta = {
+ *   damage?: number;
+ *   tapped?: boolean;
+ * };
+ *
+ * const game: GameDefinition<MyGameState, MyMoves, MyCardDef, MyCardMeta> = {
+ *   name: 'My Card Game',
+ *   zones: {
+ *     hand: { id: 'hand', name: 'Hand', visibility: 'private', ordered: false },
+ *     deck: { id: 'deck', name: 'Deck', visibility: 'secret', ordered: true },
+ *   },
+ *   setup: (players) => ({
+ *     players,
+ *     currentPlayer: 0,
+ *   }),
+ *   moves: {
+ *     playCard: {
+ *       condition: (state, context) => true,
+ *       reducer: (draft, context) => { ... }
+ *     },
+ *     pass: {
+ *       reducer: (draft) => { ... }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export type GameDefinition<
+  TState,
+  TMoves extends Record<string, any>,
+  TCardDefinition = any,
+  TCardMeta = any,
+> = {
+  /**
+   * Game name for identification and display
+   *
+   * Task 10.2: Required field
+   */
+  name: string;
+
+  /**
+   * Zone configuration (optional, but recommended for card games)
+   *
+   * Defines all zones used in the game.
+   * The framework will manage card locations and zone state internally.
+   *
+   * If zones are not provided, games must manage their own zone/card logic.
+   * This field enables the framework's internal zone management system.
+   *
+   * @example
+   * ```typescript
+   * zones: {
+   *   hand: { id: 'hand', name: 'Hand', visibility: 'private', ordered: false },
+   *   deck: { id: 'deck', name: 'Deck', visibility: 'secret', ordered: true },
+   *   play: { id: 'play', name: 'Play Area', visibility: 'public', ordered: false },
+   *   graveyard: { id: 'graveyard', name: 'Graveyard', visibility: 'public', ordered: false },
+   * }
+   * ```
+   */
+  zones?: Record<string, CardZoneConfig>;
+
+  /**
+   * Card definitions (optional)
+   *
+   * Map of card definition ID -> card data.
+   * Can be loaded dynamically or provided upfront.
+   *
+   * @example
+   * ```typescript
+   * cards: {
+   *   'pikachu': { id: 'pikachu', name: 'Pikachu', hp: 60, type: 'electric' },
+   *   'charizard': { id: 'charizard', name: 'Charizard', hp: 150, type: 'fire' },
+   * }
+   * ```
+   */
+  cards?: Record<string, TCardDefinition>;
+
+  /**
+   * Setup function - creates initial game state
+   *
+   * Task 10.4: Setup function signature
+   *
+   * Must be pure and deterministic:
+   * - Same players -> same initial state
+   * - No side effects
+   * - No randomness (use RNG in moves instead)
+   *
+   * @param players - Array of players in the game
+   * @returns Initial game state
+   */
+  setup: (players: Player[]) => TState;
+
+  /**
+   * Moves definition - exhaustive mapping of move names to move definitions
+   *
+   * Task 10.6: GameMoveDefinitions type with exhaustive mapping
+   *
+   * Each key in TMoves must have a corresponding GameMoveDefinition.
+   * Type system enforces this at compile time.
+   *
+   * Moves receive context with zones, cards operations API, and card registry.
+   */
+  moves: GameMoveDefinitions<TState, TMoves, TCardMeta, TCardDefinition>;
+
+  /**
+   * Flow definition (optional) - XState-based turn/phase/step orchestration
+   *
+   * Task 10.8: Flow configuration validation
+   *
+   * If omitted, game has no built-in flow control.
+   * Games can still progress through moves, but no automatic phase transitions.
+   */
+  flow?: FlowDefinition<TState>;
+
+  /**
+   * Tracker configuration (optional)
+   *
+   * Defines boolean flags that auto-reset at turn/phase boundaries.
+   * Eliminates boilerplate for "hasDrawnThisTurn", "hasPlayedResourceThisTurn", etc.
+   *
+   * @example
+   * ```typescript
+   * trackers: {
+   *   perTurn: ['hasDrawn', 'hasPlayedResource', 'hasAttacked'],
+   *   perPhase: {
+   *     main: ['hasPlayedCard']
+   *   },
+   *   perPlayer: true // Default: true
+   * }
+   * ```
+   */
+  trackers?: {
+    /** Trackers that reset at the end of each turn */
+    perTurn?: string[];
+    /** Trackers that reset at the end of specific phases */
+    perPhase?: Record<string, string[]>;
+    /** Whether trackers are per-player or global (default: true) */
+    perPlayer?: boolean;
+  };
+
+  /**
+   * Game end condition (optional)
+   *
+   * Task 10.10: EndIf evaluation logic
+   *
+   * Checked after every move execution.
+   * If returns a GameEndResult, the game ends.
+   * If returns undefined, game continues.
+   *
+   * @param state - Current game state
+   * @returns GameEndResult if game ended, undefined otherwise
+   */
+  endIf?: (state: TState) => GameEndResult | undefined;
+
+  /**
+   * Player view filter (optional)
+   *
+   * Task 10.12: PlayerView function signature
+   *
+   * Filters game state to hide private information from a player.
+   * If omitted, all players see complete state.
+   *
+   * Must be pure and deterministic:
+   * - Same state + playerId -> same filtered state
+   * - No side effects
+   *
+   * @param state - Complete game state
+   * @param playerId - Player requesting the view
+   * @returns Filtered state for this player
+   */
+  playerView?: (state: TState, playerId: string) => TState;
+
+  /**
+   * Telemetry hooks (optional)
+   *
+   * Callbacks for tracking game events and player actions.
+   * Hooks registered here are automatically subscribed when the engine starts.
+   *
+   * Use cases:
+   * - Analytics tracking
+   * - Error reporting
+   * - Custom logging
+   * - Performance monitoring
+   *
+   * @example
+   * ```typescript
+   * telemetryHooks: {
+   *   onPlayerAction: (event) => {
+   *     analytics.track('game.move', {
+   *       moveId: event.moveId,
+   *       playerId: event.playerId,
+   *       duration: event.duration
+   *     });
+   *   },
+   *   onEngineError: (event) => {
+   *     errorReporter.captureException(event.error, event.context);
+   *   }
+   * }
+   * ```
+   */
+  telemetryHooks?: TelemetryHooks;
+};

package/src/game-definition/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Game Definition Module
+ *
+ * Task 10: GameDefinition Type System
+ *
+ * Provides declarative game definition pattern with full type safety.
+ * Exports:
+ * - GameDefinition type (core definition)
+ * - MoveDefinition and MoveDefinitions types
+ * - Validation utilities
+ * - Supporting types (Player, GameEndResult, FlowDefinition)
+ */
+
+export type {
+  GameDefinition,
+  GameEndResult,
+  Player,
+} from "./game-definition";
+
+export type {
+  GameMoveDefinition,
+  GameMoveDefinitions,
+} from "./move-definitions";
+
+export {
+  type GameDefinitionValidationResult,
+  validateGameDefinition,
+} from "./validation";