@drmxrcy/tcg-core 0.0.0-202602060542

package/src/targeting/target-validation.ts

@@ -0,0 +1,286 @@
+import type { CardDefinition } from "../cards/card-definition";
+import type { CardInstance } from "../cards/card-instance";
+import { matchesFilter } from "../filtering/filter-matching";
+import type { CardRegistry } from "../operations/card-registry";
+import type { PlayerId } from "../types";
+import type { TargetDefinition } from "./target-definition";
+
+/**
+ * Context for target validation
+ * Provides information needed to evaluate targeting restrictions
+ * @template TCustomState - The custom state type for CardInstance
+ */
+export type TargetContext<TCustomState = unknown> = {
+  /** The card that is the source of the targeting (e.g., the spell being cast) */
+  sourceCard: CardInstance<TCustomState>;
+
+  /** The player controlling the targeting action */
+  controller: PlayerId;
+
+  /** Previously selected targets (for multi-target validation) */
+  previousTargets: CardInstance<TCustomState>[];
+};
+
+/**
+ * Result of target validation
+ */
+export type ValidationResult = {
+  valid: boolean;
+  error?: string;
+};
+
+/**
+ * Check if a card is a legal target for a given target definition
+ * @template TCustomState - The custom state type for CardInstance
+ * @template TGameState - The game state type
+ * @param card - The potential target card
+ * @param targetDef - Target definition specifying requirements
+ * @param state - Game state for filter evaluation
+ * @param registry - Card definition registry
+ * @param context - Target context (source, controller, previous targets)
+ * @returns true if the card is a legal target
+ */
+export function isLegalTarget<
+  TCustomState = unknown,
+  TGameState extends { cards: Record<string, CardInstance<TCustomState>> } = {
+    cards: Record<string, CardInstance<TCustomState>>;
+  },
+>(
+  card: CardInstance<TCustomState>,
+  targetDef: TargetDefinition,
+  state: TGameState,
+  registry: CardRegistry<CardDefinition>,
+  context: TargetContext<TCustomState>,
+): boolean {
+  // Check if card matches the filter
+  if (!matchesFilter(card, targetDef.filter, state, registry)) {
+    return false;
+  }
+
+  // Check targeting restrictions
+  if (targetDef.restrictions) {
+    for (const restriction of targetDef.restrictions) {
+      if (restriction === "not-self") {
+        if (card.id === context.sourceCard.id) {
+          return false;
+        }
+      }
+
+      if (restriction === "not-controller") {
+        if (card.controller === context.controller) {
+          return false;
+        }
+      }
+
+      if (restriction === "not-owner") {
+        if (card.owner === context.controller) {
+          return false;
+        }
+      }
+
+      if (restriction === "different-targets") {
+        if (context.previousTargets.some((target) => target.id === card.id)) {
+          return false;
+        }
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Get all legal targets for a target definition
+ * @template TCustomState - The custom state type for CardInstance
+ * @template TGameState - The game state type
+ * @param targetDef - Target definition
+ * @param state - Game state
+ * @param registry - Card definition registry
+ * @param context - Target context
+ * @returns Array of legal target cards
+ */
+export function getLegalTargets<
+  TCustomState = unknown,
+  TGameState extends { cards: Record<string, CardInstance<TCustomState>> } = {
+    cards: Record<string, CardInstance<TCustomState>>;
+  },
+>(
+  targetDef: TargetDefinition,
+  state: TGameState,
+  registry: CardRegistry<CardDefinition>,
+  context: TargetContext<TCustomState>,
+): CardInstance<TCustomState>[] {
+  const allCards = Object.values(state.cards);
+  return allCards.filter((card) =>
+    isLegalTarget(card, targetDef, state, registry, context),
+  );
+}
+
+/**
+ * Validate a target selection against a target definition
+ * @template TCustomState - The custom state type for CardInstance
+ * @template TGameState - The game state type
+ * @param targets - Selected target cards
+ * @param targetDef - Target definition
+ * @param state - Game state
+ * @param registry - Card definition registry
+ * @param context - Target context (without previousTargets)
+ * @returns Validation result
+ */
+export function validateTargetSelection<
+  TCustomState = unknown,
+  TGameState extends { cards: Record<string, CardInstance<TCustomState>> } = {
+    cards: Record<string, CardInstance<TCustomState>>;
+  },
+>(
+  targets: CardInstance<TCustomState>[],
+  targetDef: TargetDefinition,
+  state: TGameState,
+  registry: CardRegistry<CardDefinition>,
+  context: Omit<TargetContext<TCustomState>, "previousTargets">,
+): ValidationResult {
+  // Validate count
+  if (typeof targetDef.count === "number") {
+    // Exact count required
+    if (targets.length !== targetDef.count) {
+      return {
+        valid: false,
+        error: `Expected ${targetDef.count} target(s), but got ${targets.length}`,
+      };
+    }
+  } else {
+    // Range count
+    const { min, max } = targetDef.count;
+    if (targets.length < min) {
+      return {
+        valid: false,
+        error: `Expected at least ${min} target(s), but got ${targets.length}`,
+      };
+    }
+    if (targets.length > max) {
+      return {
+        valid: false,
+        error: `Expected at most ${max} target(s), but got ${targets.length}`,
+      };
+    }
+  }
+
+  // Validate each target individually
+  for (let i = 0; i < targets.length; i++) {
+    const target = targets[i];
+    if (!target) {
+      return {
+        valid: false,
+        error: `Target at index ${i} is undefined`,
+      };
+    }
+
+    const previousTargets = targets.slice(0, i);
+
+    const fullContext: TargetContext<TCustomState> = {
+      ...context,
+      previousTargets,
+    };
+
+    if (!isLegalTarget(target, targetDef, state, registry, fullContext)) {
+      return {
+        valid: false,
+        error: `Target at index ${i} (${String(target.id)}) is not a legal target`,
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Enumerate all valid target combinations for a target definition
+ * Useful for AI move generation
+ * @template TCustomState - The custom state type for CardInstance
+ * @template TGameState - The game state type
+ * @param targetDef - Target definition
+ * @param state - Game state
+ * @param registry - Card definition registry
+ * @param context - Target context
+ * @param maxCombinations - Maximum number of combinations to return
+ * @returns Array of target combinations (each combination is an array of cards)
+ */
+export function enumerateTargetCombinations<
+  TCustomState = unknown,
+  TGameState extends { cards: Record<string, CardInstance<TCustomState>> } = {
+    cards: Record<string, CardInstance<TCustomState>>;
+  },
+>(
+  targetDef: TargetDefinition,
+  state: TGameState,
+  registry: CardRegistry<CardDefinition>,
+  context: TargetContext<TCustomState>,
+  maxCombinations: number,
+): CardInstance<TCustomState>[][] {
+  const legalTargets = getLegalTargets(targetDef, state, registry, context);
+
+  // Determine count range
+  let minCount: number;
+  let maxCount: number;
+
+  if (typeof targetDef.count === "number") {
+    minCount = targetDef.count;
+    maxCount = targetDef.count;
+  } else {
+    minCount = targetDef.count.min;
+    maxCount = Math.min(targetDef.count.max, legalTargets.length);
+  }
+
+  const combinations: CardInstance<TCustomState>[][] = [];
+
+  // Helper function to generate combinations recursively
+  function generateCombinations(
+    start: number,
+    current: CardInstance<TCustomState>[],
+    targetCount: number,
+  ): void {
+    if (combinations.length >= maxCombinations) {
+      return;
+    }
+
+    if (current.length === targetCount) {
+      combinations.push([...current]);
+      return;
+    }
+
+    for (let i = start; i < legalTargets.length; i++) {
+      const candidate = legalTargets[i];
+      if (!candidate) {
+        continue;
+      }
+
+      // Check if this candidate is legal given previous selections
+      const updatedContext: TargetContext<TCustomState> = {
+        ...context,
+        previousTargets: current,
+      };
+
+      if (
+        isLegalTarget(candidate, targetDef, state, registry, updatedContext)
+      ) {
+        current.push(candidate);
+        generateCombinations(i + 1, current, targetCount);
+        current.pop();
+      }
+
+      if (combinations.length >= maxCombinations) {
+        break;
+      }
+    }
+  }
+
+  // Generate combinations for each valid count
+  for (let count = minCount; count <= maxCount; count++) {
+    generateCombinations(0, [], count);
+    if (combinations.length >= maxCombinations) {
+      break;
+    }
+  }
+
+  return combinations.slice(0, maxCombinations);
+}

package/src/telemetry/events.ts

@@ -0,0 +1,202 @@
+/**
+ * Telemetry Events
+ *
+ * Event type definitions for the TCG Core telemetry system.
+ * All events are discriminated unions for type-safe handling.
+ */
+
+import type { Patch } from "immer";
+import type { PlayerId } from "../types";
+
+/**
+ * Player Action Event
+ *
+ * Emitted whenever a player executes a move.
+ * Tracks move execution, parameters, result, and duration.
+ *
+ * Use cases:
+ * - Player behavior analysis
+ * - Move frequency tracking
+ * - Performance monitoring
+ * - Replay generation
+ */
+export type PlayerActionEvent = {
+  type: "playerAction";
+  /** Move identifier */
+  moveId: string;
+  /** Player executing the move */
+  playerId: PlayerId;
+  /** Move parameters */
+  params: unknown;
+  /** Execution result (success/failure) */
+  result: "success" | "failure";
+  /** Error message (if failed) */
+  error?: string;
+  /** Error code (if failed) */
+  errorCode?: string;
+  /** Execution duration in milliseconds */
+  duration: number;
+  /** Event timestamp */
+  timestamp: number;
+};
+
+/**
+ * State Change Event
+ *
+ * Emitted after state mutations.
+ * Contains patches for incremental state sync and replay.
+ *
+ * Use cases:
+ * - Network synchronization
+ * - State replay/reconstruction
+ * - Debugging state issues
+ * - Audit trails
+ */
+export type StateChangeEvent = {
+  type: "stateChange";
+  /** Forward patches (state mutations) */
+  patches: Patch[];
+  /** Inverse patches (for undo) */
+  inversePatches: Patch[];
+  /** Move that caused this change */
+  moveId?: string;
+  /** Optional before-state snapshot */
+  beforeSnapshot?: unknown;
+  /** Optional after-state snapshot */
+  afterSnapshot?: unknown;
+  /** Event timestamp */
+  timestamp: number;
+};
+
+/**
+ * Rule Evaluation Event
+ *
+ * Emitted during condition checks and rule evaluations.
+ * Tracks which rules fired, with what context, and the result.
+ *
+ * Use cases:
+ * - Debugging rule interactions
+ * - Understanding game decisions
+ * - AI training data
+ * - Balance analysis
+ */
+export type RuleEvaluationEvent = {
+  type: "ruleEvaluation";
+  /** Rule or condition name */
+  ruleName: string;
+  /** Evaluation result (pass/fail) */
+  result: boolean;
+  /** Evaluation context */
+  context: Record<string, unknown>;
+  /** Evaluation duration in milliseconds */
+  duration?: number;
+  /** Event timestamp */
+  timestamp: number;
+};
+
+/**
+ * Flow Transition Event
+ *
+ * Emitted during game flow transitions (phases, turns, segments).
+ * Tracks progression through game structure.
+ *
+ * Use cases:
+ * - Game pacing analysis
+ * - Turn timing metrics
+ * - Flow debugging
+ * - UI synchronization
+ */
+export type FlowTransitionEvent = {
+  type: "flowTransition";
+  /** Type of transition */
+  transitionType: "phase" | "segment" | "turn";
+  /** Source state (what we're leaving) */
+  from: string;
+  /** Destination state (where we're going) */
+  to: string;
+  /** Current turn number */
+  turn: number;
+  /** Event timestamp */
+  timestamp: number;
+};
+
+/**
+ * Engine Error Event
+ *
+ * Emitted when errors occur during engine execution.
+ * Captures full error context for debugging and monitoring.
+ *
+ * Use cases:
+ * - Error tracking and reporting
+ * - System health monitoring
+ * - Bug reproduction
+ * - Alert generation
+ */
+export type EngineErrorEvent = {
+  type: "engineError";
+  /** Error message */
+  error: string;
+  /** Stack trace */
+  stack?: string;
+  /** Error context (move, player, etc.) */
+  context: Record<string, unknown>;
+  /** Move ID (if error during move execution) */
+  moveId?: string;
+  /** Player ID (if error during player action) */
+  playerId?: PlayerId;
+  /** Event timestamp */
+  timestamp: number;
+};
+
+/**
+ * Performance Event
+ *
+ * Emitted for performance-sensitive operations.
+ * Tracks execution time and resource usage.
+ *
+ * Use cases:
+ * - Performance profiling
+ * - Bottleneck identification
+ * - Optimization validation
+ * - Resource monitoring
+ */
+export type PerformanceEvent = {
+  type: "performance";
+  /** Operation name */
+  operation: string;
+  /** Execution duration in milliseconds */
+  duration: number;
+  /** Operation metadata */
+  metadata?: Record<string, unknown>;
+  /** Event timestamp */
+  timestamp: number;
+};
+
+/**
+ * Telemetry Event Union
+ *
+ * Discriminated union of all telemetry event types.
+ * Use the `type` field for type narrowing.
+ *
+ * @example
+ * ```typescript
+ * function handleEvent(event: TelemetryEvent) {
+ *   switch (event.type) {
+ *     case 'playerAction':
+ *       console.log(`Move: ${event.moveId}, Result: ${event.result}`);
+ *       break;
+ *     case 'flowTransition':
+ *       console.log(`${event.from} -> ${event.to}`);
+ *       break;
+ *     // ... other cases
+ *   }
+ * }
+ * ```
+ */
+export type TelemetryEvent =
+  | PlayerActionEvent
+  | StateChangeEvent
+  | RuleEvaluationEvent
+  | FlowTransitionEvent
+  | EngineErrorEvent
+  | PerformanceEvent;

package/src/telemetry/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Telemetry Module
+ *
+ * Event-based telemetry system for TCG Core.
+ */
+
+export type {
+  EngineErrorEvent,
+  FlowTransitionEvent,
+  PerformanceEvent,
+  PlayerActionEvent,
+  RuleEvaluationEvent,
+  StateChangeEvent,
+  TelemetryEvent,
+} from "./events";
+export { TelemetryManager } from "./telemetry-manager";
+export type {
+  TelemetryHook,
+  TelemetryHooks,
+  TelemetryOptions,
+} from "./types";

package/src/telemetry/telemetry-manager.ts

@@ -0,0 +1,127 @@
+/**
+ * Telemetry Manager
+ *
+ * Event-based telemetry system for TCG Core.
+ * Extends EventEmitter for flexible event subscription.
+ */
+
+import { EventEmitter } from "node:events";
+import type { TelemetryEvent } from "./events";
+import type { TelemetryHooks, TelemetryOptions } from "./types";
+
+/**
+ * Telemetry Manager
+ *
+ * Manages telemetry events and hooks for the engine.
+ * Provides dual API: EventEmitter style and callback hooks.
+ */
+export class TelemetryManager extends EventEmitter {
+  private enabled: boolean;
+  private registeredHooks: TelemetryHooks;
+
+  constructor(options: TelemetryOptions) {
+    super();
+    this.enabled = options.enabled;
+    this.registeredHooks = options.hooks || {};
+
+    // Register initial hooks if provided
+    this.registerInitialHooks();
+  }
+
+  /**
+   * Register hooks provided at initialization
+   */
+  private registerInitialHooks(): void {
+    if (this.registeredHooks.onPlayerAction) {
+      this.on("playerAction", this.registeredHooks.onPlayerAction);
+    }
+    if (this.registeredHooks.onStateChange) {
+      this.on("stateChange", this.registeredHooks.onStateChange);
+    }
+    if (this.registeredHooks.onRuleEvaluation) {
+      this.on("ruleEvaluation", this.registeredHooks.onRuleEvaluation);
+    }
+    if (this.registeredHooks.onFlowTransition) {
+      this.on("flowTransition", this.registeredHooks.onFlowTransition);
+    }
+    if (this.registeredHooks.onEngineError) {
+      this.on("engineError", this.registeredHooks.onEngineError);
+    }
+    if (this.registeredHooks.onPerformance) {
+      this.on("onPerformance", this.registeredHooks.onPerformance);
+    }
+  }
+
+  /**
+   * Emit telemetry event
+   *
+   * Emits events via EventEmitter and invokes registered hooks.
+   * Does nothing if telemetry is disabled.
+   *
+   * @param event - Telemetry event to emit
+   * @returns True if emitted, false if disabled
+   */
+  emitEvent(event: TelemetryEvent): boolean {
+    if (!this.enabled) {
+      return false;
+    }
+
+    // Emit via EventEmitter (for runtime subscribers)
+    super.emit(event.type, event);
+
+    return true;
+  }
+
+  /**
+   * Register a single telemetry hook
+   *
+   * Allows external systems to subscribe to specific event types.
+   */
+  registerHook<K extends keyof TelemetryHooks>(
+    eventType: K,
+    handler: NonNullable<TelemetryHooks[K]>,
+  ): void {
+    this.registeredHooks[eventType] = handler;
+
+    // Register with EventEmitter
+    // Remove 'on' prefix for event name
+    const eventName = eventType.startsWith("on")
+      ? eventType.slice(2, 3).toLowerCase() + eventType.slice(3)
+      : eventType;
+
+    this.on(eventName, handler as (...args: unknown[]) => void);
+  }
+
+  /**
+   * Unregister a telemetry hook
+   */
+  unregisterHook<K extends keyof TelemetryHooks>(
+    eventType: K,
+    handler: NonNullable<TelemetryHooks[K]>,
+  ): void {
+    if (this.registeredHooks[eventType] === handler) {
+      delete this.registeredHooks[eventType];
+    }
+
+    // Unregister from EventEmitter
+    const eventName = eventType.startsWith("on")
+      ? eventType.slice(2, 3).toLowerCase() + eventType.slice(3)
+      : eventType;
+
+    this.off(eventName, handler as (...args: unknown[]) => void);
+  }
+
+  /**
+   * Set enabled state
+   */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Check if telemetry is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+}

package/src/telemetry/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Telemetry Types
+ *
+ * Type definitions for the TCG Core telemetry system.
+ * Provides hooks for external analytics and monitoring systems.
+ */
+
+import type {
+  EngineErrorEvent,
+  FlowTransitionEvent,
+  PerformanceEvent,
+  PlayerActionEvent,
+  RuleEvaluationEvent,
+  StateChangeEvent,
+  TelemetryEvent,
+} from "./events";
+
+/**
+ * Telemetry Hook
+ *
+ * Generic callback type for handling telemetry events.
+ * All hooks receive a single event parameter and return void.
+ */
+export type TelemetryHook = (event: TelemetryEvent) => void;
+
+/**
+ * Telemetry Hooks
+ *
+ * Object defining callbacks for specific event types.
+ * Each hook is optional and receives only events of its type.
+ */
+export type TelemetryHooks = {
+  /** Called when a player executes a move */
+  onPlayerAction?: (event: PlayerActionEvent) => void;
+  /** Called when state changes occur */
+  onStateChange?: (event: StateChangeEvent) => void;
+  /** Called when rules are evaluated */
+  onRuleEvaluation?: (event: RuleEvaluationEvent) => void;
+  /** Called during flow transitions (phase/turn/segment) */
+  onFlowTransition?: (event: FlowTransitionEvent) => void;
+  /** Called when engine errors occur */
+  onEngineError?: (event: EngineErrorEvent) => void;
+  /** Called for performance metrics */
+  onPerformance?: (event: PerformanceEvent) => void;
+};
+
+/**
+ * Telemetry Options
+ *
+ * Configuration for TelemetryManager instances.
+ */
+export type TelemetryOptions = {
+  /**
+   * Enable/disable telemetry
+   *
+   * When false, no events are emitted.
+   * Default: false
+   */
+  enabled: boolean;
+
+  /**
+   * Event hooks
+   *
+   * Optional callbacks for specific event types.
+   * Invoked synchronously when events are emitted.
+   */
+  hooks?: TelemetryHooks;
+};