@drmxrcy/tcg-core 0.0.0-202602060542

package/src/moves/move-executor.test.ts

@@ -0,0 +1,431 @@
+import { describe, expect, it } from "bun:test";
+import type { Draft } from "immer";
+import type { GameMoveDefinition } from "../game-definition/move-definitions";
+import { createMockContext } from "../testing/test-context-factory";
+import type { PlayerId } from "../types";
+import { createPlayerId } from "../types";
+import {
+  canExecuteMove,
+  executeMove,
+  getMove,
+  getMoveIds,
+  moveExists,
+} from "./move-executor";
+import type { MoveContext } from "./move-system";
+
+describe("Move Executor", () => {
+  type TestGameState = {
+    players: Record<PlayerId, { life: number; mana: number }>;
+    turnCount: number;
+  };
+
+  const player1 = createPlayerId("p1");
+  const player2 = createPlayerId("p2");
+
+  const initialState: TestGameState = {
+    players: {
+      [player1]: { life: 20, mana: 5 },
+      [player2]: { life: 20, mana: 5 },
+    },
+    turnCount: 1,
+  };
+
+  const testMoves: Record<string, GameMoveDefinition<TestGameState>> = {
+    "spend-mana": {
+      condition: (state: TestGameState, context: MoveContext) =>
+        state.players[context.playerId].mana >= 2,
+      reducer: (draft: Draft<TestGameState>, context: MoveContext) => {
+        draft.players[context.playerId].mana -= 2;
+      },
+    },
+    "deal-damage": {
+      condition: (state: TestGameState, context: MoveContext) => {
+        if (!context.targets?.[0]) return false;
+        const targetId = context.targets[0][0] as PlayerId;
+        return targetId in state.players;
+      },
+      reducer: (draft: Draft<TestGameState>, context: MoveContext) => {
+        const targetId = context.targets?.[0]?.[0] as PlayerId;
+        if (targetId) {
+          draft.players[targetId].life -= 3;
+        }
+      },
+    },
+    "next-turn": {
+      reducer: (draft: Draft<TestGameState>) => {
+        draft.turnCount += 1;
+      },
+    },
+  };
+
+  describe("executeMove", () => {
+    it("should execute valid move successfully", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const result = executeMove(
+        initialState,
+        "spend-mana",
+        context,
+        testMoves,
+      );
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.state.players[player1].mana).toBe(3);
+        expect(result.state.players[player2].mana).toBe(5); // Unchanged
+      }
+    });
+
+    it("should reject move with failed condition", () => {
+      const lowManaState: TestGameState = {
+        ...initialState,
+        players: {
+          ...initialState.players,
+          [player1]: { life: 20, mana: 1 },
+        },
+      };
+
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const result = executeMove(
+        lowManaState,
+        "spend-mana",
+        context,
+        testMoves,
+      );
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("condition not met");
+        expect(result.errorCode).toBe("CONDITION_FAILED");
+      }
+    });
+
+    it("should reject non-existent move", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const result = executeMove(
+        initialState,
+        "nonexistent",
+        context,
+        testMoves,
+      );
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("does not exist");
+        expect(result.errorCode).toBe("MOVE_NOT_FOUND");
+      }
+    });
+
+    it("should execute move without condition", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const result = executeMove(initialState, "next-turn", context, testMoves);
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.state.turnCount).toBe(2);
+      }
+    });
+
+    it("should execute move with targets", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+        targets: [[player2]],
+      });
+      const result = executeMove(
+        initialState,
+        "deal-damage",
+        context,
+        testMoves,
+      );
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.state.players[player2].life).toBe(17);
+      }
+    });
+
+    it("should handle condition errors gracefully", () => {
+      const brokenMove: GameMoveDefinition<TestGameState> = {
+        condition: () => {
+          throw new Error("Condition error");
+        },
+        reducer: (draft: Draft<TestGameState>) => draft,
+      };
+
+      const moves = { ...testMoves, broken: brokenMove };
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const result = executeMove(initialState, "broken", context, moves);
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.errorCode).toBe("CONDITION_ERROR");
+        expect(result.error).toContain("Error checking condition");
+      }
+    });
+
+    it("should handle reducer errors gracefully", () => {
+      const brokenMove: GameMoveDefinition<TestGameState> = {
+        reducer: () => {
+          throw new Error("Reducer error");
+        },
+      };
+
+      const moves = { ...testMoves, "broken-reducer": brokenMove };
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const result = executeMove(
+        initialState,
+        "broken-reducer",
+        context,
+        moves,
+      );
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.errorCode).toBe("EXECUTION_ERROR");
+        expect(result.error).toContain("Error executing move");
+      }
+    });
+
+    it("should not mutate original state", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      executeMove(initialState, "spend-mana", context, testMoves);
+
+      // Original state should be unchanged
+      expect(initialState.players[player1].mana).toBe(5);
+    });
+  });
+
+  describe("canExecuteMove", () => {
+    it("should return true for valid move", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const canExecute = canExecuteMove(
+        initialState,
+        "spend-mana",
+        context,
+        testMoves,
+      );
+
+      expect(canExecute).toBe(true);
+    });
+
+    it("should return false for invalid move", () => {
+      const lowManaState: TestGameState = {
+        ...initialState,
+        players: {
+          ...initialState.players,
+          [player1]: { life: 20, mana: 1 },
+        },
+      };
+
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const canExecute = canExecuteMove(
+        lowManaState,
+        "spend-mana",
+        context,
+        testMoves,
+      );
+
+      expect(canExecute).toBe(false);
+    });
+
+    it("should return false for non-existent move", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const canExecute = canExecuteMove(
+        initialState,
+        "nonexistent",
+        context,
+        testMoves,
+      );
+
+      expect(canExecute).toBe(false);
+    });
+
+    it("should return true for move without condition", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const canExecute = canExecuteMove(
+        initialState,
+        "next-turn",
+        context,
+        testMoves,
+      );
+
+      expect(canExecute).toBe(true);
+    });
+
+    it("should not execute the move (dry run)", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      canExecuteMove(initialState, "spend-mana", context, testMoves);
+
+      // State should be unchanged
+      expect(initialState.players[player1].mana).toBe(5);
+    });
+
+    it("should handle condition errors by returning false", () => {
+      const brokenMove: GameMoveDefinition<TestGameState> = {
+        condition: () => {
+          throw new Error("Condition error");
+        },
+        reducer: (draft: Draft<TestGameState>) => draft,
+      };
+
+      const moves = { ...testMoves, broken: brokenMove };
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+      const canExecute = canExecuteMove(initialState, "broken", context, moves);
+
+      expect(canExecute).toBe(false);
+    });
+  });
+
+  describe("getMove", () => {
+    it("should return move definition if exists", () => {
+      const move = getMove("spend-mana", testMoves);
+
+      expect(move).toBeDefined();
+      expect(move?.reducer).toBeDefined();
+    });
+
+    it("should return undefined if move does not exist", () => {
+      const move = getMove("nonexistent", testMoves);
+
+      expect(move).toBeUndefined();
+    });
+  });
+
+  describe("getMoveIds", () => {
+    it("should return all move IDs", () => {
+      const ids = getMoveIds(testMoves);
+
+      expect(ids).toContain("spend-mana");
+      expect(ids).toContain("deal-damage");
+      expect(ids).toContain("next-turn");
+      expect(ids).toHaveLength(3);
+    });
+
+    it("should return empty array for empty moves", () => {
+      const ids = getMoveIds({});
+
+      expect(ids).toEqual([]);
+    });
+  });
+
+  describe("moveExists", () => {
+    it("should return true if move exists", () => {
+      expect(moveExists("spend-mana", testMoves)).toBe(true);
+      expect(moveExists("deal-damage", testMoves)).toBe(true);
+    });
+
+    it("should return false if move does not exist", () => {
+      expect(moveExists("nonexistent", testMoves)).toBe(false);
+    });
+  });
+
+  describe("Integration: Validation Pipeline", () => {
+    it("should follow full validation pipeline", () => {
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+
+      // 1. Check if move can be executed
+      const canExecute = canExecuteMove(
+        initialState,
+        "spend-mana",
+        context,
+        testMoves,
+      );
+      expect(canExecute).toBe(true);
+
+      // 2. Execute the move
+      const result = executeMove(
+        initialState,
+        "spend-mana",
+        context,
+        testMoves,
+      );
+      expect(result.success).toBe(true);
+
+      // 3. Use new state
+      if (result.success) {
+        const newState = result.state;
+        expect(newState.players[player1].mana).toBe(3);
+
+        // 4. Check if move can still be executed
+        const canExecuteAgain = canExecuteMove(
+          newState,
+          "spend-mana",
+          context,
+          testMoves,
+        );
+        expect(canExecuteAgain).toBe(true); // Still >= 2 mana
+      }
+    });
+
+    it("should prevent invalid moves from being executed", () => {
+      const lowManaState: TestGameState = {
+        ...initialState,
+        players: {
+          ...initialState.players,
+          [player1]: { life: 20, mana: 1 },
+        },
+      };
+
+      const context: MoveContext = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+
+      // Pre-check prevents unnecessary execution
+      if (canExecuteMove(lowManaState, "spend-mana", context, testMoves)) {
+        const result = executeMove(
+          lowManaState,
+          "spend-mana",
+          context,
+          testMoves,
+        );
+        expect(result.success).toBe(true);
+      } else {
+        // Move was correctly prevented
+        expect(true).toBe(true);
+      }
+    });
+  });
+});

package/src/moves/move-executor.ts

@@ -0,0 +1,195 @@
+import { produce } from "immer";
+import type { GameMoveDefinition } from "../game-definition/move-definitions";
+import type { MoveContext, MoveResult } from "./move-system";
+
+/**
+ * Generic move map type for runtime lookup
+ *
+ * Used by executor functions that need to look up moves by string ID.
+ * For type-safe move definitions in game definitions, use GameMoveDefinitions instead.
+ */
+type GenericMoveMap<TGameState> = Record<
+  string,
+  GameMoveDefinition<TGameState>
+>;
+
+/**
+ * Execute a move with full validation pipeline
+ *
+ * Pipeline:
+ * 1. Validate move exists
+ * 2. Check condition (if present)
+ * 3. Execute reducer with Immer
+ * 4. Return result (success or failure)
+ *
+ * @param state - Current game state
+ * @param moveId - ID of move to execute
+ * @param context - Move context
+ * @param moves - Available moves
+ * @returns MoveResult with new state or error
+ *
+ * @example
+ * ```typescript
+ * const result = executeMove(
+ *   gameState,
+ *   'draw-card',
+ *   { playerId: 'p1' },
+ *   gameMoves
+ * );
+ *
+ * if (result.success) {
+ *   gameState = result.state;
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+export function executeMove<TGameState>(
+  state: TGameState,
+  moveId: string,
+  context: MoveContext,
+  moves: GenericMoveMap<TGameState>,
+): MoveResult<TGameState> {
+  // 1. Validate move exists
+  const moveDef = moves[moveId];
+  if (!moveDef) {
+    return {
+      success: false,
+      error: `Move '${moveId}' does not exist`,
+      errorCode: "MOVE_NOT_FOUND",
+      errorContext: { moveId },
+    };
+  }
+
+  // 2. Check condition
+  if (moveDef.condition) {
+    try {
+      const isValid = moveDef.condition(state, context);
+      if (!isValid) {
+        return {
+          success: false,
+          error: `Move '${moveId}' condition not met`,
+          errorCode: "CONDITION_FAILED",
+          errorContext: { moveId },
+        };
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: `Error checking condition for move '${moveId}': ${error instanceof Error ? error.message : String(error)}`,
+        errorCode: "CONDITION_ERROR",
+        errorContext: {
+          moveId,
+          originalError: error instanceof Error ? error.message : String(error),
+        },
+      };
+    }
+  }
+
+  // 3. Execute reducer
+  try {
+    const nextState = produce(state, (draft) => {
+      moveDef.reducer(draft, context);
+    });
+
+    return {
+      success: true,
+      state: nextState,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Error executing move '${moveId}': ${error instanceof Error ? error.message : String(error)}`,
+      errorCode: "EXECUTION_ERROR",
+      errorContext: {
+        moveId,
+        originalError: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+/**
+ * Check if a move can be executed without actually executing it
+ *
+ * Validates:
+ * 1. Move exists
+ * 2. Condition passes (if present)
+ *
+ * Does NOT execute the reducer or modify state.
+ *
+ * @param state - Current game state
+ * @param moveId - ID of move to check
+ * @param context - Move context
+ * @param moves - Available moves
+ * @returns True if move can be executed
+ *
+ * @example
+ * ```typescript
+ * if (canExecuteMove(gameState, 'play-card', context, moves)) {
+ *   const result = executeMove(gameState, 'play-card', context, moves);
+ * }
+ * ```
+ */
+export function canExecuteMove<TGameState>(
+  state: TGameState,
+  moveId: string,
+  context: MoveContext,
+  moves: GenericMoveMap<TGameState>,
+): boolean {
+  const moveDef = moves[moveId];
+  if (!moveDef) {
+    return false;
+  }
+
+  if (!moveDef.condition) {
+    return true; // No condition means always valid
+  }
+
+  try {
+    const result = moveDef.condition(state, context);
+    return result === true; // Support both boolean and ConditionFailure returns
+  } catch {
+    return false; // Condition error = invalid
+  }
+}
+
+/**
+ * Get move definition by ID
+ *
+ * @param moveId - ID of move to retrieve
+ * @param moves - Available moves
+ * @returns Move definition or undefined
+ */
+export function getMove<TGameState>(
+  moveId: string,
+  moves: GenericMoveMap<TGameState>,
+): GameMoveDefinition<TGameState> | undefined {
+  return moves[moveId];
+}
+
+/**
+ * Get all move IDs
+ *
+ * @param moves - Available moves
+ * @returns Array of move IDs
+ */
+export function getMoveIds<TGameState>(
+  moves: GenericMoveMap<TGameState>,
+): string[] {
+  return Object.keys(moves);
+}
+
+/**
+ * Check if a move exists
+ *
+ * @param moveId - ID of move to check
+ * @param moves - Available moves
+ * @returns True if move exists
+ */
+export function moveExists<TGameState>(
+  moveId: string,
+  moves: GenericMoveMap<TGameState>,
+): boolean {
+  return moveId in moves;
+}