roll-parser 2.3.2 → 3.0.0-alpha.0

package/src/evaluator/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Evaluator module - AST to roll result transformation.
+ *
+ * @module evaluator
+ */
+
+export { DEFAULT_MAX_DICE, evaluate, EvaluatorError } from './evaluator';
+export {
+  applyDropHighest,
+  applyDropLowest,
+  applyKeepHighest,
+  applyKeepLowest,
+  sumKeptDice,
+} from './modifiers/keep-drop';

package/src/evaluator/modifiers/compare.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared comparison helper for dice-pool modifiers.
+ *
+ * Both reroll and success-counting modifiers compare a die result against a
+ * fixed threshold. Extracting the comparison keeps those modules free of
+ * duplicated logic.
+ *
+ * @module evaluator/modifiers/compare
+ */
+
+import type { CompareOp } from '../../types';
+
+/**
+ * Compares a die result against a fixed comparison threshold.
+ */
+export function matchesCondition(result: number, operator: CompareOp, value: number): boolean {
+  switch (operator) {
+    case '>':
+      return result > value;
+    case '>=':
+      return result >= value;
+    case '<':
+      return result < value;
+    case '<=':
+      return result <= value;
+    case '=':
+      return result === value;
+  }
+}

package/src/evaluator/modifiers/explode.ts

@@ -0,0 +1,215 @@
+/**
+ * Exploding dice modifier implementations.
+ *
+ * Standard (`!`): re-roll on match, append each new die to the pool.
+ * Compound (`!!`): re-roll on match, accumulate into the original die's `result`.
+ * Penetrating (`!p`): re-roll on match, append with `result = rawRoll - 1`.
+ *
+ * @module evaluator/modifiers/explode
+ */
+
+import type { RNG } from '../../rng/types';
+import type { CompareOp } from '../../types';
+import type { DieResult } from '../../types';
+import { EvaluatorError, type EvalEnv } from '../evaluator';
+
+/** Default maximum explosion iterations per die. */
+export const DEFAULT_MAX_EXPLODE_ITERATIONS = 1_000;
+
+/**
+ * Predicate deciding whether a die with the given latest raw roll continues
+ * to explode. `sides` is passed separately because the default predicate
+ * ("explode on max face") uses `result === sides`.
+ */
+export type ShouldExplode = (rawResult: number, sides: number) => boolean;
+
+/**
+ * Builds an explosion predicate from an optional ComparePoint. When no
+ * threshold is given, explode when the raw result equals the die's max face.
+ */
+export function buildShouldExplode(
+  operator: CompareOp | undefined,
+  thresholdValue: number | undefined,
+): ShouldExplode {
+  if (operator == null || thresholdValue == null) {
+    return (result, sides) => result === sides;
+  }
+  switch (operator) {
+    case '>':
+      return (result) => result > thresholdValue;
+    case '>=':
+      return (result) => result >= thresholdValue;
+    case '<':
+      return (result) => result < thresholdValue;
+    case '<=':
+      return (result) => result <= thresholdValue;
+    case '=':
+      return (result) => result === thresholdValue;
+  }
+}
+
+/**
+ * Rolls one explosion die, charging it against the global dice limit.
+ */
+function rollExplosion(sides: number, rng: RNG, env: EvalEnv): number {
+  if (env.totalDiceRolled + 1 > env.maxDice) {
+    throw new EvaluatorError(
+      `Total dice count ${env.totalDiceRolled + 1} exceeds limit of ${env.maxDice}`,
+      'DICE_LIMIT_EXCEEDED',
+      'Explode',
+    );
+  }
+  env.totalDiceRolled += 1;
+  return rng.nextInt(1, sides);
+}
+
+function explodeLimitError(maxIterations: number): EvaluatorError {
+  return new EvaluatorError(
+    `Explode iteration limit of ${maxIterations} exceeded`,
+    'EXPLODE_LIMIT_EXCEEDED',
+    'Explode',
+  );
+}
+
+/**
+ * Returns true when the die is eligible to start exploding: it must not
+ * already be dropped by a prior modifier, and its `sides` must be rollable.
+ *
+ * Fate dice (sides = 0) are skipped defensively — `rng.nextInt(1, 0)` is
+ * invalid. Fate + explode is out of scope for the current feature set.
+ */
+function canExplode(die: DieResult): boolean {
+  if (die.modifiers.includes('dropped')) return false;
+  if (die.sides < 1) return false;
+  return true;
+}
+
+/**
+ * Standard explode: append each new die to the pool. The original die keeps
+ * its modifiers untouched; new dice carry `['exploded', 'kept']`.
+ */
+export function applyStandardExplode(
+  pool: DieResult[],
+  shouldExplode: ShouldExplode,
+  rng: RNG,
+  env: EvalEnv,
+): DieResult[] {
+  const result: DieResult[] = [];
+
+  for (const original of pool) {
+    result.push(original);
+    if (!canExplode(original)) continue;
+
+    const sides = original.sides;
+    let last = original.result;
+    let iterations = 0;
+
+    while (shouldExplode(last, sides)) {
+      if (iterations >= env.maxExplodeIterations) {
+        throw explodeLimitError(env.maxExplodeIterations);
+      }
+      const next = rollExplosion(sides, rng, env);
+      result.push({
+        sides,
+        result: next,
+        modifiers: ['exploded', 'kept'],
+        critical: next === sides && sides > 1,
+        fumble: next === 1,
+      });
+      last = next;
+      iterations += 1;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Compound explode: pool length stays the same. Each original die's `result`
+ * accumulates every explosion roll, and gains the `'exploded'` modifier once
+ * it actually exploded at least once.
+ */
+export function applyCompoundExplode(
+  pool: DieResult[],
+  shouldExplode: ShouldExplode,
+  rng: RNG,
+  env: EvalEnv,
+): DieResult[] {
+  return pool.map((original) => {
+    if (!canExplode(original)) return original;
+
+    const sides = original.sides;
+    let accumulated = original.result;
+    let last = original.result;
+    let iterations = 0;
+    let exploded = false;
+
+    while (shouldExplode(last, sides)) {
+      if (iterations >= env.maxExplodeIterations) {
+        throw explodeLimitError(env.maxExplodeIterations);
+      }
+      const next = rollExplosion(sides, rng, env);
+      accumulated += next;
+      last = next;
+      exploded = true;
+      iterations += 1;
+    }
+
+    if (!exploded) return original;
+
+    return {
+      sides,
+      result: accumulated,
+      modifiers: original.modifiers.includes('exploded')
+        ? original.modifiers
+        : [...original.modifiers, 'exploded'],
+      // ? `critical` and `fumble` refer to the original triggering roll, but
+      //   after compounding the `result` is a sum. Mark critical if the
+      //   original roll was max; fumble stays as-is (can't accumulate down).
+      critical: original.critical,
+      fumble: original.fumble,
+    };
+  });
+}
+
+/**
+ * Penetrating explode: like standard, but each appended die stores
+ * `result = rawRoll - 1`. The explosion predicate runs on the RAW roll
+ * (pre-decrement), matching rpg-dice-roller convention.
+ */
+export function applyPenetratingExplode(
+  pool: DieResult[],
+  shouldExplode: ShouldExplode,
+  rng: RNG,
+  env: EvalEnv,
+): DieResult[] {
+  const result: DieResult[] = [];
+
+  for (const original of pool) {
+    result.push(original);
+    if (!canExplode(original)) continue;
+
+    const sides = original.sides;
+    let lastRaw = original.result;
+    let iterations = 0;
+
+    while (shouldExplode(lastRaw, sides)) {
+      if (iterations >= env.maxExplodeIterations) {
+        throw explodeLimitError(env.maxExplodeIterations);
+      }
+      const raw = rollExplosion(sides, rng, env);
+      const stored = raw - 1;
+      result.push({
+        sides,
+        result: stored,
+        modifiers: ['exploded', 'kept'],
+        critical: raw === sides && sides > 1,
+        fumble: raw === 1,
+      });
+      lastRaw = raw;
+      iterations += 1;
+    }
+  }
+
+  return result;
+}

package/src/evaluator/modifiers/keep-drop.ts

@@ -0,0 +1,151 @@
+/**
+ * Keep/drop modifier implementations for dice pools.
+ *
+ * @module evaluator/modifiers/keep-drop
+ */
+
+import type { DieResult } from '../../types';
+
+/**
+ * Marks all eligible dice as `'kept'`. Dice that already carry `'dropped'`
+ * (e.g., intermediate rerolls, or the loser of a prior modifier) are left
+ * untouched so those drops cannot be silently revived.
+ */
+export function markAllKept(dice: DieResult[]): DieResult[] {
+  return dice.map((die) => {
+    if (die.modifiers.includes('dropped')) return die;
+    return {
+      ...die,
+      modifiers: die.modifiers.includes('kept') ? die.modifiers : [...die.modifiers, 'kept'],
+    };
+  });
+}
+
+/**
+ * Returns indexed dice that are eligible for keep/drop selection — dice that
+ * have not already been dropped by a preceding modifier (e.g. reroll's
+ * intermediate dice carry `'dropped'` and must be ignored here).
+ */
+function eligibleIndexed(dice: DieResult[]): { die: DieResult; index: number }[] {
+  return dice
+    .map((die, index) => ({ die, index }))
+    .filter(({ die }) => !die.modifiers.includes('dropped'));
+}
+
+/**
+ * Rebuilds a die's slot flags (`kept` / `dropped`) from the selection set.
+ * Pre-dropped dice are returned unchanged so their state is preserved.
+ */
+function applySelection(
+  dice: DieResult[],
+  selectionIndices: Set<number>,
+  selectionMarker: 'kept' | 'dropped',
+): DieResult[] {
+  const otherMarker = selectionMarker === 'kept' ? 'dropped' : 'kept';
+
+  return dice.map((die, index) => {
+    if (die.modifiers.includes('dropped')) return die;
+
+    const isSelected = selectionIndices.has(index);
+    const marker = isSelected ? selectionMarker : otherMarker;
+
+    return {
+      ...die,
+      modifiers: [...die.modifiers.filter((m) => m !== 'kept' && m !== 'dropped'), marker],
+    };
+  });
+}
+
+/**
+ * Drops every non-already-dropped die. Used by keep-N when N <= 0 and by
+ * drop-N when N >= eligible.length.
+ */
+function markAllDropped(dice: DieResult[]): DieResult[] {
+  return dice.map((die) => {
+    if (die.modifiers.includes('dropped')) return die;
+    return {
+      ...die,
+      modifiers: [...die.modifiers.filter((m) => m !== 'kept'), 'dropped'],
+    };
+  });
+}
+
+/**
+ * Applies keep highest modifier - keeps the N highest eligible dice, marks
+ * others as dropped. Dice already marked `'dropped'` are left unchanged.
+ *
+ * @param dice - Array of die results
+ * @param count - Number of dice to keep
+ * @returns New array with appropriate modifiers applied
+ */
+export function applyKeepHighest(dice: DieResult[], count: number): DieResult[] {
+  const eligible = eligibleIndexed(dice);
+
+  if (count >= eligible.length) return markAllKept(dice);
+  if (count <= 0) return markAllDropped(dice);
+
+  const sorted = [...eligible].sort((a, b) => b.die.result - a.die.result);
+  const keptIndices = new Set(sorted.slice(0, count).map((item) => item.index));
+
+  return applySelection(dice, keptIndices, 'kept');
+}
+
+/**
+ * Applies keep lowest modifier - keeps the N lowest eligible dice, marks
+ * others as dropped. Dice already marked `'dropped'` are left unchanged.
+ */
+export function applyKeepLowest(dice: DieResult[], count: number): DieResult[] {
+  const eligible = eligibleIndexed(dice);
+
+  if (count >= eligible.length) return markAllKept(dice);
+  if (count <= 0) return markAllDropped(dice);
+
+  const sorted = [...eligible].sort((a, b) => a.die.result - b.die.result);
+  const keptIndices = new Set(sorted.slice(0, count).map((item) => item.index));
+
+  return applySelection(dice, keptIndices, 'kept');
+}
+
+/**
+ * Applies drop highest modifier - drops the N highest eligible dice, keeps
+ * the rest. Dice already marked `'dropped'` are left unchanged.
+ */
+export function applyDropHighest(dice: DieResult[], count: number): DieResult[] {
+  const eligible = eligibleIndexed(dice);
+
+  if (count <= 0) return markAllKept(dice);
+  if (count >= eligible.length) return markAllDropped(dice);
+
+  const sorted = [...eligible].sort((a, b) => b.die.result - a.die.result);
+  const droppedIndices = new Set(sorted.slice(0, count).map((item) => item.index));
+
+  return applySelection(dice, droppedIndices, 'dropped');
+}
+
+/**
+ * Applies drop lowest modifier - drops the N lowest eligible dice, keeps
+ * the rest. Dice already marked `'dropped'` are left unchanged.
+ */
+export function applyDropLowest(dice: DieResult[], count: number): DieResult[] {
+  const eligible = eligibleIndexed(dice);
+
+  if (count <= 0) return markAllKept(dice);
+  if (count >= eligible.length) return markAllDropped(dice);
+
+  const sorted = [...eligible].sort((a, b) => a.die.result - b.die.result);
+  const droppedIndices = new Set(sorted.slice(0, count).map((item) => item.index));
+
+  return applySelection(dice, droppedIndices, 'dropped');
+}
+
+/**
+ * Calculates total from dice, excluding dropped dice.
+ *
+ * @param dice - Array of die results
+ * @returns Sum of non-dropped dice
+ */
+export function sumKeptDice(dice: DieResult[]): number {
+  return dice
+    .filter((die) => !die.modifiers.includes('dropped'))
+    .reduce((sum, die) => sum + die.result, 0);
+}

package/src/evaluator/modifiers/reroll.ts

@@ -0,0 +1,172 @@
+/**
+ * Reroll modifier implementations.
+ *
+ * Recursive (`r`): re-roll matching dice until the condition no longer holds,
+ *   or the per-die iteration limit is reached.
+ * Reroll-once (`ro`): re-roll matching dice exactly once, keeping the second
+ *   result regardless of whether it matches.
+ *
+ * @module evaluator/modifiers/reroll
+ */
+
+import type { RNG } from '../../rng/types';
+import type { CompareOp, DieResult } from '../../types';
+import { EvaluatorError, type EvalEnv } from '../evaluator';
+import { matchesCondition } from './compare';
+
+/** Default maximum reroll iterations per die. */
+export const DEFAULT_MAX_REROLL_ITERATIONS = 1_000;
+
+export { matchesCondition };
+
+/**
+ * Rolls a replacement die for the given sides, charging it against the global
+ * dice limit. Fate dice (sides === 0) re-roll on the {-1, 0, +1} range.
+ */
+function rollReplacement(sides: number, rng: RNG, env: EvalEnv): DieResult {
+  if (env.totalDiceRolled + 1 > env.maxDice) {
+    throw new EvaluatorError(
+      `Total dice count ${env.totalDiceRolled + 1} exceeds limit of ${env.maxDice}`,
+      'DICE_LIMIT_EXCEEDED',
+      'Reroll',
+    );
+  }
+  env.totalDiceRolled += 1;
+
+  if (sides === 0) {
+    const result = rng.nextInt(-1, 1);
+    return {
+      sides: 0,
+      result,
+      modifiers: [],
+      critical: false,
+      fumble: false,
+    };
+  }
+
+  const result = rng.nextInt(1, sides);
+  return {
+    sides,
+    result,
+    modifiers: [],
+    critical: result === sides && sides > 1,
+    fumble: result === 1,
+  };
+}
+
+function rerollLimitError(maxIterations: number): EvaluatorError {
+  return new EvaluatorError(
+    `Reroll iteration limit of ${maxIterations} exceeded`,
+    'REROLL_LIMIT_EXCEEDED',
+    'Reroll',
+  );
+}
+
+/**
+ * True for dice eligible to start rerolling. Dropped dice (from a preceding
+ * keep/drop modifier) are left alone.
+ */
+function canReroll(die: DieResult): boolean {
+  return !die.modifiers.includes('dropped');
+}
+
+/**
+ * Returns the die's modifiers with any "slot" flags removed. Slot flags
+ * (`kept`, `dropped`, `rerolled`) are controlled by the surrounding logic
+ * and should be reassigned each pass.
+ */
+function stripSlotFlags(modifiers: DieResult['modifiers']): DieResult['modifiers'] {
+  return modifiers.filter((m) => m !== 'kept' && m !== 'dropped' && m !== 'rerolled');
+}
+
+/**
+ * Applies recursive reroll: re-roll each matching die until it no longer
+ * matches or the per-die iteration limit is reached. Intermediate dice are
+ * appended to the output pool with `['rerolled', 'dropped']` so they:
+ * 1. Render as strikethrough (via `renderDice`'s `'dropped'` check).
+ * 2. Are excluded from `sumKeptDice`.
+ * 3. Are ignored by subsequent keep/drop modifiers.
+ */
+export function applyRecursiveReroll(
+  pool: DieResult[],
+  operator: CompareOp,
+  value: number,
+  rng: RNG,
+  env: EvalEnv,
+): DieResult[] {
+  const result: DieResult[] = [];
+
+  for (const original of pool) {
+    if (!canReroll(original)) {
+      result.push(original);
+      continue;
+    }
+
+    let current = original;
+    let iterations = 0;
+
+    while (matchesCondition(current.result, operator, value)) {
+      if (iterations >= env.maxRerollIterations) {
+        throw rerollLimitError(env.maxRerollIterations);
+      }
+
+      result.push({
+        ...current,
+        modifiers: [...stripSlotFlags(current.modifiers), 'rerolled', 'dropped'],
+      });
+
+      current = rollReplacement(current.sides, rng, env);
+      iterations += 1;
+    }
+
+    result.push({
+      ...current,
+      modifiers: [...stripSlotFlags(current.modifiers), 'kept'],
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Applies reroll-once: re-roll each matching die exactly once, keeping the
+ * second result regardless of whether it matches. Non-matching dice pass
+ * through with the `'kept'` slot flag.
+ */
+export function applyRerollOnce(
+  pool: DieResult[],
+  operator: CompareOp,
+  value: number,
+  rng: RNG,
+  env: EvalEnv,
+): DieResult[] {
+  const result: DieResult[] = [];
+
+  for (const original of pool) {
+    if (!canReroll(original)) {
+      result.push(original);
+      continue;
+    }
+
+    if (!matchesCondition(original.result, operator, value)) {
+      result.push({
+        ...original,
+        modifiers: [...stripSlotFlags(original.modifiers), 'kept'],
+      });
+      continue;
+    }
+
+    result.push({
+      ...original,
+      modifiers: [...stripSlotFlags(original.modifiers), 'rerolled', 'dropped'],
+    });
+
+    const replacement = rollReplacement(original.sides, rng, env);
+    result.push({
+      ...replacement,
+      modifiers: [...stripSlotFlags(replacement.modifiers), 'kept'],
+    });
+  }
+
+  return result;
+}

package/src/evaluator/modifiers/success-count.ts

@@ -0,0 +1,59 @@
+/**
+ * Success counting modifier.
+ *
+ * Transforms a dice pool into a signed success count: each die matching the
+ * success `threshold` contributes +1, each die matching the optional
+ * `failThreshold` contributes -1. When a single die matches both thresholds,
+ * success wins (checked first).
+ *
+ * Dropped dice (from a preceding keep/drop or intermediate reroll) are
+ * excluded from counting and are never tagged.
+ *
+ * Mutates the input pool in place to add `'success'` / `'failure'` modifier
+ * flags — mirrors the mutation pattern of explode and reroll modifiers.
+ *
+ * @module evaluator/modifiers/success-count
+ */
+
+import type { CompareOp, DieResult } from '../../types';
+import { matchesCondition } from './compare';
+
+export type ResolvedThreshold = {
+  operator: CompareOp;
+  value: number;
+};
+
+export type SuccessCountResult = {
+  total: number;
+  successes: number;
+  failures: number;
+};
+
+export function countSuccesses(
+  dice: DieResult[],
+  threshold: ResolvedThreshold,
+  failThreshold?: ResolvedThreshold,
+): SuccessCountResult {
+  let successes = 0;
+  let failures = 0;
+
+  for (const die of dice) {
+    if (die.modifiers.includes('dropped')) continue;
+
+    if (matchesCondition(die.result, threshold.operator, threshold.value)) {
+      die.modifiers.push('success');
+      successes += 1;
+      continue;
+    }
+
+    if (
+      failThreshold != null &&
+      matchesCondition(die.result, failThreshold.operator, failThreshold.value)
+    ) {
+      die.modifiers.push('failure');
+      failures += 1;
+    }
+  }
+
+  return { total: successes - failures, successes, failures };
+}