@drmxrcy/tcg-core 0.0.0-202602060542

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

@@ -0,0 +1,188 @@
+import type { Draft } from "immer";
+import type { MoveContext, NormalizeParams } from "../moves/move-system";
+
+/**
+ * Game Move Definition
+ *
+ * Task 10.5, 10.6: Implement GameMoveDefinition with reducer and optional condition
+ *
+ * Declarative definition of a single move/action in the game.
+ * Each move has:
+ * - A reducer function (required) - executes the move with typed parameters
+ * - An optional condition function - validates if move is legal
+ * - Optional metadata - for categorization, UI, etc.
+ *
+ * @template TState - Game state type
+ * @template TParams - Move-specific parameter type (from TMoves[MoveName])
+ * @template TCardMeta - Card metadata type (for zone/card operations)
+ * @template TCardDefinition - Card definition type (for registry access)
+ */
+export type GameMoveDefinition<
+  TState,
+  TParams = any,
+  TCardMeta = any,
+  TCardDefinition = any,
+> = {
+  /**
+   * Move reducer - executes the move using Immer draft
+   *
+   * Task 10.6: Reducer with Immer draft pattern
+   *
+   * Pure function that mutates the draft to update state.
+   * Immer converts mutations into immutable updates.
+   *
+   * The context includes fully-typed parameters specific to this move.
+   *
+   * @param draft - Immer draft (mutable proxy) of game state
+   * @param context - Move context (player, typed params, targets, timestamp, zones, cards, registry)
+   *
+   * @example
+   * ```typescript
+   * // For a move: playCard: { cardId: string; alternativeCost?: AlternativeCost }
+   * reducer: (draft, context) => {
+   *   const { cardId, alternativeCost } = context.params; // ✅ Fully typed!
+   *   // Implementation...
+   * }
+   * ```
+   */
+  reducer: (
+    draft: Draft<TState>,
+    context: MoveContext<NormalizeParams<TParams>, TCardMeta, TCardDefinition>,
+  ) => void;
+
+  /**
+   * Move condition - validates if move is legal
+   *
+   * Task 10.6: Optional condition for validation
+   *
+   * Pure predicate checked BEFORE reducer execution.
+   * If returns false, move is rejected without state changes.
+   *
+   * The context includes fully-typed parameters specific to this move.
+   *
+   * @param state - Current game state (readonly)
+   * @param context - Move context (player, typed params, targets, timestamp, zones, cards, registry)
+   * @returns True if move is legal, false otherwise
+   *
+   * @example
+   * ```typescript
+   * // For a move: playCard: { cardId: string; alternativeCost?: AlternativeCost }
+   * condition: (state, context) => {
+   *   const { cardId, alternativeCost } = context.params; // ✅ Fully typed!
+   *   // Validation logic...
+   * }
+   * ```
+   */
+  condition?: (
+    state: TState,
+    context: MoveContext<NormalizeParams<TParams>, TCardMeta, TCardDefinition>,
+  ) => boolean | import("../moves/move-system").ConditionFailure;
+
+  /**
+   * Parameter enumerator (for move enumeration system)
+   *
+   * Optional function to generate candidate parameter combinations.
+   * Used by RuleEngine.enumerateMoves() to discover available moves for AI/UI.
+   * Each parameter combination returned will be validated against the move's condition.
+   *
+   * If not provided, move will still appear in enumeration results
+   * but will indicate that parameters are required.
+   *
+   * @example
+   * ```typescript
+   * enumerator: (state, context) => {
+   *   // Get all cards in player's hand
+   *   const handCards = context.zones.getCardsInZone('hand', context.playerId);
+   *   // Generate parameter for each card
+   *   return handCards.map(cardId => ({ cardId }));
+   * }
+   * ```
+   */
+  enumerator?: (
+    state: TState,
+    context: import("../moves/move-enumeration").MoveEnumerationContext<
+      TCardMeta,
+      TCardDefinition
+    >,
+  ) => TParams[];
+
+  /**
+   * Optional metadata
+   *
+   * For categorization, UI display, AI hints, etc.
+   * Not used by engine, but available to game implementations.
+   */
+  metadata?: {
+    /** Move category (e.g., 'combat', 'resource', 'draw') */
+    category?: string;
+    /** Tags for filtering/searching */
+    tags?: string[];
+    /** Custom metadata */
+    [key: string]: unknown;
+  };
+};
+
+/**
+ * Game Move Definitions - Exhaustive mapping of moves with type-safe parameters
+ *
+ * Task 10.6: GameMoveDefinitions type with exhaustive mapping
+ *
+ * Maps each move name in TMoves to its GameMoveDefinition with the correct parameter type.
+ * TypeScript enforces that:
+ * - All moves in TMoves have definitions
+ * - No extra moves are defined
+ * - Each definition has the correct parameter type (TMoves[K])
+ * - Reducers and conditions receive fully-typed parameters via context.params
+ *
+ * @template TState - Game state type
+ * @template TMoves - Record of move names to parameter types
+ * @template TCardMeta - Card metadata type
+ * @template TCardDefinition - Card definition type
+ *
+ * @example
+ * ```typescript
+ * type MyMoves = {
+ *   playCard: { cardId: string; cost?: number };
+ *   quest: { cardId: string };
+ *   pass: void;
+ * };
+ *
+ * const moves: GameMoveDefinitions<GameState, MyMoves> = {
+ *   playCard: {
+ *     condition: (state, context) => {
+ *       const { cardId, cost } = context.params; // ✅ Typed as { cardId: string; cost?: number }
+ *       return true;
+ *     },
+ *     reducer: (draft, context) => {
+ *       const { cardId, cost } = context.params; // ✅ Typed as { cardId: string; cost?: number }
+ *       // Implementation...
+ *     }
+ *   },
+ *   quest: {
+ *     reducer: (draft, context) => {
+ *       const { cardId } = context.params; // ✅ Typed as { cardId: string }
+ *       // Implementation...
+ *     }
+ *   },
+ *   pass: {
+ *     reducer: (draft, context) => {
+ *       // context.params is {} (empty object)
+ *       // Implementation...
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export type GameMoveDefinitions<
+  TState,
+  TMoves extends Record<string, any>,
+  TCardMeta = any,
+  TCardDefinition = any,
+> = {
+  [K in keyof TMoves]: GameMoveDefinition<
+    TState,
+    TMoves[K], // ✅ Each move gets its specific parameter type!
+    TCardMeta,
+    TCardDefinition
+  >;
+};

package/src/game-definition/validation.ts

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import type { GameDefinition } from "./game-definition";
+
+/**
+ * Game Definition Validation Result
+ *
+ * Result of validating a GameDefinition.
+ */
+export type GameDefinitionValidationResult =
+  | { success: true }
+  | { success: false; error: string; errors?: string[] };
+
+/**
+ * Zod schema for GameDefinition validation
+ *
+ * Task 10.14: Implement Zod schema for GameDefinition validation
+ *
+ * Runtime validation to ensure GameDefinition is well-formed.
+ * Checks:
+ * - Required fields are present
+ * - Types are correct (functions, numbers, strings)
+ * - Constraints are met (minPlayers <= maxPlayers, etc.)
+ */
+const GameDefinitionSchema = z.object({
+  // Name validation
+  name: z.string().min(1, "Game name must not be empty"),
+
+  // Setup function validation
+  setup: z.function().args(z.array(z.string())).returns(z.record(z.any())),
+
+  // Moves validation
+  moves: z.record(
+    z.object({
+      reducer: z.function(),
+      condition: z.function().optional(),
+      metadata: z.record(z.any()).optional(),
+    }),
+  ),
+
+  // Optional flow validation
+  flow: z
+    .object({
+      initial: z.string(),
+      states: z.record(z.any()),
+      hooks: z
+        .object({
+          onBegin: z.function().optional(),
+          onEnd: z.function().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+
+  // Optional endIf validation
+  endIf: z
+    .function()
+    .args(z.any())
+    .returns(
+      z.union([
+        z.object({ winner: z.string(), reason: z.string() }),
+        z.undefined(),
+      ]),
+    )
+    .optional(),
+
+  // Optional playerView validation
+  playerView: z
+    .function()
+    .args(z.any(), z.string())
+    .returns(z.any())
+    .optional(),
+});
+
+/**
+ * Validate GameDefinition
+ *
+ * Task 10.13, 10.14: Validate GameDefinition using Zod schema
+ *
+ * Performs comprehensive validation:
+ * 1. Schema validation (types, required fields)
+ * 3. Move definition validation (each move has reducer)
+ * 4. Function signature validation
+ *
+ * @param definition - GameDefinition to validate
+ * @returns GameDefinitionValidationResult with success flag and error details
+ */
+export function validateGameDefinition<
+  TState,
+  TMoves extends Record<string, any>,
+>(definition: GameDefinition<TState, TMoves>): GameDefinitionValidationResult {
+  const errors: string[] = [];
+
+  try {
+    // Run Zod schema validation
+    GameDefinitionSchema.parse(definition);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      // Collect all Zod validation errors
+      for (const issue of error.issues) {
+        const path = issue.path.join(".");
+        errors.push(`${path}: ${issue.message}`);
+      }
+    } else {
+      errors.push("Unknown validation error");
+    }
+  }
+
+  // Validate that setup is a function
+  if (typeof definition.setup !== "function") {
+    errors.push("setup must be a function");
+  }
+
+  // Validate that moves exist and have reducers
+  if (!definition.moves || typeof definition.moves !== "object") {
+    errors.push("moves must be an object");
+  } else {
+    for (const [moveName, moveDef] of Object.entries(definition.moves)) {
+      if (!moveDef || typeof moveDef !== "object") {
+        errors.push(`Move "${moveName}" must be an object`);
+        continue;
+      }
+
+      if (typeof moveDef.reducer !== "function") {
+        errors.push(`Move "${moveName}" must have a reducer function`);
+      }
+
+      if (moveDef.condition && typeof moveDef.condition !== "function") {
+        errors.push(`Move "${moveName}" condition must be a function`);
+      }
+    }
+  }
+
+  // Validate optional endIf
+  if (definition.endIf && typeof definition.endIf !== "function") {
+    errors.push("endIf must be a function");
+  }
+
+  // Validate optional playerView
+  if (definition.playerView && typeof definition.playerView !== "function") {
+    errors.push("playerView must be a function");
+  }
+
+  // Validate optional flow
+  if (definition.flow) {
+    if (typeof definition.flow !== "object") {
+      errors.push("flow must be an object");
+    } else {
+      // Flow validation - supports both simplified (turn) and full (gameSegments) syntax
+      const flow = definition.flow as any;
+
+      // Check for simplified syntax (turn property)
+      const hasSimplifiedSyntax = "turn" in flow && flow.turn;
+
+      // Check for full syntax (gameSegments property)
+      const hasFullSyntax = "gameSegments" in flow && flow.gameSegments;
+
+      if (!(hasSimplifiedSyntax || hasFullSyntax)) {
+        errors.push(
+          "flow must have either 'turn' property (simplified) or 'gameSegments' property (full syntax)",
+        );
+      } else if (hasSimplifiedSyntax) {
+        // Validate simplified syntax
+        if (typeof flow.turn !== "object") {
+          errors.push("flow.turn must be an object");
+        } else if (!flow.turn.phases || typeof flow.turn.phases !== "object") {
+          errors.push("flow.turn must have phases object");
+        }
+      }
+      // Full syntax validation could be added here if needed
+    }
+  }
+
+  // Return result
+  if (errors.length > 0) {
+    return {
+      success: false,
+      error: errors.join("; "),
+      errors,
+    };
+  }
+
+  return { success: true };
+}