roll-parser 3.0.0-beta.0 → 3.0.0

package/src/evaluator/modifiers/crit-threshold.ts

@@ -19,10 +19,7 @@
 
 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';
+import { isVersusDc } from './flags.js';
 
 /**
  * Applies success/fail threshold arrays to a dice pool, overriding each
@@ -36,7 +33,7 @@ export function applyCritThresholds(
   failThresholds: ResolvedCritThreshold[],
 ): void {
   for (const die of dice) {
-    if (die.modifiers.includes('meta')) continue;
+    if (die.modifiers.includes('meta') || isVersusDc(die)) continue;
 
     die.critical = successThresholds.some((t) => matchesCrit(t, die));
     die.fumble = failThresholds.some((t) => matchesFumble(t, die));
@@ -52,7 +49,7 @@ function matchesCrit(threshold: ResolvedCritThreshold, die: DieResult): boolean
 
 function matchesFumble(threshold: ResolvedCritThreshold, die: DieResult): boolean {
   if (threshold === 'default') {
-    // ? Mirrors `createDieResult` — a d1 always rolls 1, never a fumble.
+    // 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/die-bound.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-die clamp modifier (`minN` / `maxN`).
+ *
+ * Rewrites each die's `result` toward the bound: `min` raises results below
+ * the bound, `max` lowers results above it. The raw face is preserved in
+ * `initialResult` (first writer wins, so a compound-explode accumulation
+ * that was clamped afterwards still reports its original first roll), and
+ * the die is tagged `'min'` / `'max'` so parts consumers can tell a clamped
+ * value from a natural one.
+ *
+ * `critical` / `fumble` keep reflecting the natural face — a clamped 1 is
+ * still a fumble, matching the raw-face crit semantics used everywhere else.
+ * Meta dice (rolled to compute counts/sides/modifier args) are skipped.
+ * Dropped dice are clamped too — they are excluded from totals anyway, and
+ * clamping them keeps the rendered pool consistent.
+ *
+ * @module evaluator/modifiers/die-bound
+ */
+
+import type { DieResult } from '../../types.js';
+import { isVersusDc } from './flags.js';
+
+/**
+ * Clamps every non-meta die in `dice` against `value`, in place.
+ * `bound: 'min'` lifts lower results up to `value`; `'max'` caps higher
+ * results down to it. Untouched dice keep their tags.
+ */
+export function applyDieBound(dice: DieResult[], bound: 'min' | 'max', value: number): void {
+  for (const die of dice) {
+    if (die.modifiers.includes('meta') || isVersusDc(die)) continue;
+
+    const clamped = bound === 'min' ? Math.max(die.result, value) : Math.min(die.result, value);
+    if (clamped === die.result) continue;
+
+    die.initialResult ??= die.result;
+    die.result = clamped;
+    die.modifiers.push(bound);
+  }
+}

package/src/evaluator/modifiers/explode.ts

@@ -8,12 +8,22 @@
  * @module evaluator/modifiers/explode
  */
 
+import { EvaluatorError } from '../../errors.js';
 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';
+import type { CompareOp, DieResult } from '../../types.js';
+import { createDieResult } from '../die.js';
+import { chargeDie, type EvalEnv } from '../env.js';
+import { isVersusDc } from './flags.js';
 
-/** Default maximum explosion iterations per die. */
+/**
+ * Default value of `EvaluationOptions.maxExplodeIterations`: how many times a
+ * single die may explode before `EXPLODE_LIMIT_EXCEEDED` is thrown.
+ *
+ * Per die, not per pool — it bounds notations like `1d1!`, where the
+ * explosion condition can never stop being true.
+ *
+ * @category Limits
+ */
 export const DEFAULT_MAX_EXPLODE_ITERATIONS = 1_000;
 
 /**
@@ -52,14 +62,7 @@ export function buildShouldExplode(
  * 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;
+  chargeDie(env, 'Explode');
   return rng.nextInt(1, sides);
 }
 
@@ -82,20 +85,27 @@ function explodeLimitError(maxIterations: number): EvaluatorError {
  * can never be reached if a future AST path slips past the parser gate.
  */
 function canExplode(die: DieResult): boolean {
+  if (isVersusDc(die)) return false;
   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']`.
+ * Shared implementation of the two appending explode variants. The explosion
+ * predicate always runs on the RAW roll; `storeResult` maps that raw roll to
+ * the value recorded on the appended die, which is the only thing standard
+ * and penetrating explosions disagree about.
+ *
+ * `critical`/`fumble` are likewise derived from the raw roll — a penetrating
+ * die that rolled its max face is still a crit even though it stores one less.
  */
-export function applyStandardExplode(
+function applyAppendingExplode(
   pool: DieResult[],
   shouldExplode: ShouldExplode,
   rng: RNG,
   env: EvalEnv,
+  storeResult: (raw: number) => number,
 ): DieResult[] {
   const result: DieResult[] = [];
 
@@ -104,22 +114,18 @@ export function applyStandardExplode(
     if (!canExplode(original)) continue;
 
     const sides = original.sides;
-    let last = original.result;
+    let lastRaw = original.result;
     let iterations = 0;
 
-    while (shouldExplode(last, sides)) {
+    while (shouldExplode(lastRaw, 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;
+      const raw = rollExplosion(sides, rng, env);
+      const die = createDieResult(sides, raw, ['exploded', 'kept']);
+      die.result = storeResult(raw);
+      result.push(die);
+      lastRaw = raw;
       iterations += 1;
     }
   }
@@ -127,6 +133,29 @@ export function applyStandardExplode(
   return result;
 }
 
+/** Records the raw roll unchanged — standard explode. */
+function keepRaw(raw: number): number {
+  return raw;
+}
+
+/** Records one less than the raw roll — penetrating explode. */
+function penetratingPenalty(raw: number): number {
+  return raw - 1;
+}
+
+/**
+ * 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[] {
+  return applyAppendingExplode(pool, shouldExplode, rng, env, keepRaw);
+}
+
 /**
  * Compound explode: pool length stays the same. Each original die's `result`
  * accumulates every explosion roll, and gains the `'exploded'` modifier once
@@ -164,8 +193,8 @@ export function applyCompoundExplode(
 
     if (!exploded) continue;
 
-    // ? `critical` and `fumble` keep referring to the original triggering
-    //   roll — after compounding the `result` is a sum.
+    // `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')) {
@@ -179,7 +208,8 @@ export function applyCompoundExplode(
 /**
  * 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.
+ * (pre-decrement), so a max face still chains even though its stored value
+ * is one lower.
  */
 export function applyPenetratingExplode(
   pool: DieResult[],
@@ -187,33 +217,5 @@ export function applyPenetratingExplode(
   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;
+  return applyAppendingExplode(pool, shouldExplode, rng, env, penetratingPenalty);
 }

package/src/evaluator/modifiers/flags.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared slot-flag rewriting for `DieResult.modifiers`.
+ *
+ * "Slot" flags (`kept` / `dropped` / `rerolled`) and tally flags
+ * (`success` / `failure`) are owned by whichever pass is currently deciding a
+ * die's fate, so each pass rebuilds them rather than appending. Every rewrite
+ * site strips its own exclusion list and appends its own markers — the lists
+ * differ, the mechanics do not.
+ *
+ * @module evaluator/modifiers/flags
+ */
+
+import type { DieModifier, DieResult } from '../../types.js';
+
+/**
+ * True when a die belongs to the DC side of a `vs` comparison.
+ *
+ * DC dice share the roll side's `rolls` array so they still render
+ * (`1d20[3] vs 2d10[5, 6]`), but they are not part of the pool a modifier
+ * operates on. Nothing may sum, select, clamp, reroll, explode, or tally them
+ * — a `d10` on the DC side must never come back clamped to 20, and
+ * `{1d20 vs 2d10, 1d4}>=5` must not count the DC faces as successes.
+ */
+export function isVersusDc(die: DieResult): boolean {
+  return die.modifiers.includes('dc');
+}
+
+/** Kept/dropped selection flags — rebuilt by every keep/drop pass. */
+export const SELECTION_FLAGS: readonly DieModifier[] = ['kept', 'dropped'];
+
+/**
+ * Selection flags plus the success-count tally flags. Stripped when a die
+ * leaves the pool that tagged it (meta sub-expressions, dropped group
+ * sub-rolls) so the top-level successes/failures scan cannot count it.
+ */
+export const SELECTION_AND_TALLY_FLAGS: readonly DieModifier[] = [
+  'kept',
+  'dropped',
+  'success',
+  'failure',
+];
+
+/** Selection flags plus `rerolled` — reassigned on every reroll pass. */
+export const REROLL_SLOT_FLAGS: readonly DieModifier[] = ['kept', 'dropped', 'rerolled'];
+
+/** Returns `modifiers` with every flag in `excluded` removed. */
+export function stripFlags(
+  modifiers: readonly DieModifier[],
+  excluded: readonly DieModifier[],
+): DieModifier[] {
+  return modifiers.filter((modifier) => !excluded.includes(modifier));
+}
+
+/** Returns `modifiers` with `excluded` removed and `added` appended, in order. */
+export function rewriteFlags(
+  modifiers: readonly DieModifier[],
+  excluded: readonly DieModifier[],
+  ...added: DieModifier[]
+): DieModifier[] {
+  return [...stripFlags(modifiers, excluded), ...added];
+}

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

@@ -4,138 +4,131 @@
  * @module evaluator/modifiers/keep-drop
  */
 
-import type { DieResult } from '../../types.js';
+import type { DieResult, KeepDropSpec } from '../../types.js';
+import { isVersusDc } from './flags.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'],
-    };
-  });
-}
+/** One selectable die: its rolled value and its slot in the original pool. */
+type EligibleDie = { result: number; index: number };
 
 /**
- * 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.
+ * Records into `droppedMask` every pool slot that `kind` / `selector` /
+ * `count` drops.
  *
- * @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.
+ * Nothing is cloned and no flag is written. The caller owns the merge, so a
+ * chain like `4d6kh3dl1` runs one pass per spec over the same mask and then
+ * rewrites each die's slot flags exactly once — where the previous
+ * clone-per-spec appliers rebuilt the whole pool for every spec only to have
+ * their flags read back and discarded.
+ *
+ * Dice already carrying `'dropped'` (reroll intermediates, meta dice, a
+ * preceding chain's losers) are ineligible for selection and stay dropped.
  */
-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');
+export function markDroppedIndices(
+  dice: DieResult[],
+  count: number,
+  kind: KeepDropSpec['kind'],
+  selector: KeepDropSpec['selector'],
+  droppedMask: Uint8Array,
+): void {
+  if (count === 1) {
+    markSingleExtreme(dice, kind, selector, droppedMask);
+    return;
+  }
+
+  const eligible: EligibleDie[] = [];
+
+  for (let index = 0; index < dice.length; index++) {
+    const die = dice[index];
+    if (die == null) continue;
+    if (isVersusDc(die)) continue;
+
+    if (die.modifiers.includes('dropped')) {
+      droppedMask[index] = 1;
+      continue;
+    }
+
+    eligible.push({ result: die.result, index });
+  }
+
+  const isKeep = kind === 'keep';
+
+  // Keep-everything: a keep covering the whole eligible pool, or a zero drop.
+  if (isKeep ? count >= eligible.length : count <= 0) return;
+
+  // Drop-everything: a zero keep, or a drop covering the whole eligible pool.
+  if (isKeep ? count <= 0 : count >= eligible.length) {
+    for (const item of eligible) {
+      droppedMask[item.index] = 1;
+    }
+    return;
+  }
+
+  // Stable sort — ties resolve by original pool order.
+  eligible.sort(
+    selector === 'highest' ? (a, b) => b.result - a.result : (a, b) => a.result - b.result,
+  );
+
+  // The sort puts the acted-on dice first: `keep` drops everything past
+  // `count`, `drop` drops the selection itself.
+  const start = isKeep ? count : 0;
+  const end = isKeep ? eligible.length : count;
+
+  for (let i = start; i < end; i++) {
+    const item = eligible[i];
+    if (item != null) droppedMask[item.index] = 1;
+  }
 }
 
 /**
- * Applies drop lowest modifier - drops the N lowest eligible dice, keeps
- * the rest. Dice already marked `'dropped'` are left unchanged.
+ * `count === 1` fast path: a single linear scan replaces the wrapper array
+ * and comparator sort — `2d20kh1` (advantage) and `4d6dl1` are the most
+ * common notations. Strict comparison preserves the stable sort's
+ * first-occurrence tie-break, and bits are only ever set, never cleared, so
+ * a shared mask keeps every previous spec's drops.
  */
-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');
+function markSingleExtreme(
+  dice: DieResult[],
+  kind: KeepDropSpec['kind'],
+  selector: KeepDropSpec['selector'],
+  droppedMask: Uint8Array,
+): void {
+  const isKeep = kind === 'keep';
+  const wantHighest = selector === 'highest';
+
+  let extremeIndex = -1;
+  let extremeResult = 0;
+
+  for (let index = 0; index < dice.length; index++) {
+    const die = dice[index];
+    if (die == null) continue;
+    if (isVersusDc(die)) continue;
+
+    if (die.modifiers.includes('dropped')) {
+      droppedMask[index] = 1;
+      continue;
+    }
+
+    const { result } = die;
+
+    if (extremeIndex === -1) {
+      extremeIndex = index;
+      extremeResult = result;
+      continue;
+    }
+
+    if (wantHighest ? result > extremeResult : result < extremeResult) {
+      // A keep drops the dethroned extreme; a drop keeps everything else.
+      if (isKeep) droppedMask[extremeIndex] = 1;
+      extremeIndex = index;
+      extremeResult = result;
+    } else if (isKeep) {
+      droppedMask[index] = 1;
+    }
+  }
+
+  // Keeping 1 of ≤1 eligible dice drops nothing; dropping 1 of ≥1 drops the
+  // extreme — both match the general path's whole-pool guards.
+  if (!isKeep && extremeIndex !== -1) droppedMask[extremeIndex] = 1;
 }
 
 /**
@@ -145,7 +138,12 @@ export function applyDropLowest(dice: DieResult[], count: number): DieResult[] {
  * @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);
+  let total = 0;
+
+  for (const die of dice) {
+    if (isVersusDc(die)) continue;
+    if (!die.modifiers.includes('dropped')) total += die.result;
+  }
+
+  return total;
 }