roll-parser 2.3.2 → 3.0.0-beta.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.js';
+export {
+  applyDropHighest,
+  applyDropLowest,
+  applyKeepHighest,
+  applyKeepLowest,
+  sumKeptDice,
+} from './modifiers/keep-drop.js';

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.js';
+
+/**
+ * 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/crit-threshold.ts

@@ -0,0 +1,59 @@
+/**
+ * Critical / fumble threshold modifier.
+ *
+ * Overrides the default `critical`/`fumble` flag logic for a dice pool.
+ * `cs` and `cf` are independent (Roll20 semantics): the evaluator passes
+ * `['default']` for a side with no explicit thresholds, so overriding one
+ * side never wipes the other. An empty threshold array (not produced by the
+ * evaluator) would force the corresponding flag to `false` on every die.
+ * Meta dice (rolled to compute counts/sides/modifier args) are skipped so
+ * their bookkeeping stays untouched.
+ *
+ * Display-only: does not alter `total`, explosion triggers, success
+ * counting, or any other modifier flag. Dropped dice still participate —
+ * their `critical`/`fumble` metadata reflects what they rolled, not
+ * whether they contributed to the total.
+ *
+ * @module evaluator/modifiers/crit-threshold
+ */
+
+import type { DieResult, ResolvedCritThreshold } from '../../types.js';
+import { matchesCondition } from './compare.js';
+
+// ? Re-exported for existing importers — the definition moved to types.ts so
+//   the public RollPart union can reference it without a circular import.
+export type { ResolvedCritThreshold } from '../../types.js';
+
+/**
+ * Applies success/fail threshold arrays to a dice pool, overriding each
+ * die's `critical` and `fumble` flags in place. A die matches `'default'`
+ * on the success side when `result === sides && sides > 1`, and on the
+ * fail side when `result === 1`. Meta dice are skipped.
+ */
+export function applyCritThresholds(
+  dice: DieResult[],
+  successThresholds: ResolvedCritThreshold[],
+  failThresholds: ResolvedCritThreshold[],
+): void {
+  for (const die of dice) {
+    if (die.modifiers.includes('meta')) continue;
+
+    die.critical = successThresholds.some((t) => matchesCrit(t, die));
+    die.fumble = failThresholds.some((t) => matchesFumble(t, die));
+  }
+}
+
+function matchesCrit(threshold: ResolvedCritThreshold, die: DieResult): boolean {
+  if (threshold === 'default') {
+    return die.result === die.sides && die.sides > 1;
+  }
+  return matchesCondition(die.result, threshold.operator, threshold.value);
+}
+
+function matchesFumble(threshold: ResolvedCritThreshold, die: DieResult): boolean {
+  if (threshold === 'default') {
+    // ? Mirrors `createDieResult` — a d1 always rolls 1, never a fumble.
+    return die.result === 1 && die.sides > 1;
+  }
+  return matchesCondition(die.result, threshold.operator, threshold.value);
+}

package/src/evaluator/modifiers/explode.ts

@@ -0,0 +1,219 @@
+/**
+ * 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.js';
+import type { CompareOp } from '../../types.js';
+import type { DieResult } from '../../types.js';
+import { EvaluatorError, type EvalEnv } from '../evaluator.js';
+
+/** 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.
+ *
+ * The `sides < 1` branch is a defense-in-depth fallback — Fate dice
+ * (sides = 0) are rejected at parse time via `INVALID_EXPLODE_TARGET`
+ * (see `parseExplode` in `src/parser/parser.ts`), so this guard should
+ * never fire during normal flow. Keeping it ensures `rng.nextInt(1, 0)`
+ * can never be reached if a future AST path slips past the parser gate.
+ */
+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 && sides > 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.
+ *
+ * Mutates exploded dice in place — the same `DieResult` objects are shared
+ * between `RollResult.rolls` and the `RollPart` tree, and both must reflect
+ * post-explosion state.
+ */
+export function applyCompoundExplode(
+  pool: DieResult[],
+  shouldExplode: ShouldExplode,
+  rng: RNG,
+  env: EvalEnv,
+): DieResult[] {
+  for (const original of pool) {
+    if (!canExplode(original)) continue;
+
+    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) continue;
+
+    // ? `critical` and `fumble` keep referring to the original triggering
+    //   roll — after compounding the `result` is a sum.
+    original.initialResult = original.result;
+    original.result = accumulated;
+    if (!original.modifiers.includes('exploded')) {
+      original.modifiers = [...original.modifiers, 'exploded'];
+    }
+  }
+
+  return pool;
+}
+
+/**
+ * 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 && sides > 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.js';
+
+/**
+ * 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,165 @@
+/**
+ * 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.js';
+import type { CompareOp, DieResult } from '../../types.js';
+import { EvaluatorError, type EvalEnv } from '../evaluator.js';
+import { matchesCondition } from './compare.js';
+
+/** 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 && sides > 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;
+
+    // ? Mutate flags in place — the same DieResult objects are shared with
+    //   the RollPart tree, and both views must reflect reroll state.
+    while (matchesCondition(current.result, operator, value)) {
+      if (iterations >= env.maxRerollIterations) {
+        throw rerollLimitError(env.maxRerollIterations);
+      }
+
+      current.modifiers = [...stripSlotFlags(current.modifiers), 'rerolled', 'dropped'];
+      result.push(current);
+
+      current = rollReplacement(current.sides, rng, env);
+      iterations += 1;
+    }
+
+    current.modifiers = [...stripSlotFlags(current.modifiers), 'kept'];
+    result.push(current);
+  }
+
+  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;
+    }
+
+    // ? Mutate flags in place — see `applyRecursiveReroll`.
+    if (!matchesCondition(original.result, operator, value)) {
+      original.modifiers = [...stripSlotFlags(original.modifiers), 'kept'];
+      result.push(original);
+      continue;
+    }
+
+    original.modifiers = [...stripSlotFlags(original.modifiers), 'rerolled', 'dropped'];
+    result.push(original);
+
+    const replacement = rollReplacement(original.sides, rng, env);
+    replacement.modifiers = [...stripSlotFlags(replacement.modifiers), 'kept'];
+    result.push(replacement);
+  }
+
+  return result;
+}

package/src/evaluator/modifiers/sort.ts

@@ -0,0 +1,30 @@
+/**
+ * Sort modifier implementation.
+ *
+ * Sort is purely cosmetic — it reorders the dice produced by its target in
+ * ascending or descending order of `result` without touching any flag
+ * (`kept`, `dropped`, `critical`, `fumble`, `rerolled`, `meta`) or the total.
+ * Dropped dice stay in the pool and sort alongside kept dice so readers can
+ * see where the dropped value landed in the ordered sequence.
+ *
+ * @module evaluator/modifiers/sort
+ */
+
+import type { DieResult } from '../../types.js';
+
+/**
+ * Returns a sorted copy of `dice` in the given order, preserving every die's
+ * original flags and metadata. Comparison is on `.result` — the raw face
+ * value is what the user sees in rendered output, so ordering by raw value
+ * matches the visual intent regardless of any `kept`/`dropped` flagging.
+ *
+ * Relies on `Array.prototype.sort` being stable — equal-valued dice retain
+ * their original insertion order.
+ */
+export function sortDice(dice: DieResult[], order: 'ascending' | 'descending'): DieResult[] {
+  const cmp =
+    order === 'ascending'
+      ? (a: DieResult, b: DieResult) => a.result - b.result
+      : (a: DieResult, b: DieResult) => b.result - a.result;
+  return [...dice].sort(cmp);
+}