roll-parser 3.0.0-beta.0 → 3.1.0

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

@@ -9,6 +9,40 @@
  * Meta dice (rolled to compute counts/sides/modifier args) are skipped so
  * their bookkeeping stays untouched.
  *
+ * The two threshold kinds deliberately read different values. `'default'`
+ * reads `initialResult ?? result`, the same source as the versus `natural`,
+ * so "rolled the maximum face" survives the two modifiers that overwrite
+ * `result` while recording the face they replaced — compound explode and
+ * `minN`/`maxN`. An explicit threshold (`cs>4`, `cf<=2`) reads the die's
+ * current `result`: it is a predicate over the die's value, and postfix
+ * modifiers are order-sensitive by design, so `4d6min5cs>4` is meant to
+ * see the clamped faces. The two can therefore disagree on one die —
+ * `4d6min5cs>4` flags a clamped natural 1 as both critical and fumble.
+ *
+ * They also diverge on Fate dice. `'default'` carries a `sides > 1` guard, so
+ * it never fires on a `sides = 0` pool; an explicit threshold has none and
+ * compares the raw {-1, 0, +1} face, so `4dFcs>0` and `4dFcf=-1` do set the
+ * flags. The missing guard is deliberate — the parser rejects the bare
+ * `cs`/`cf` forms instead, since they would resolve to `'default'` and
+ * silently do nothing.
+ *
+ * ! Penetrating explode is not covered: it stores `raw - 1` in `result`
+ * ! without recording `initialResult`, so `1d6!pcs` still judges a natural
+ * ! 6 by its decremented 5. An *inherited* rule is handed the raw roll
+ * ! instead, which keeps `1d6cf>5!p` agreeing with `1d6!p` on the side the
+ * ! user never overrode — at the cost of `1d6cf>5!p` and `1d6!pcf>5`
+ * ! disagreeing on it. Recording `initialResult` here would settle both, but
+ * ! `extractNatural` reads that field to tell an appended explosion die from
+ * ! a compounded one, and would start counting these as versus primaries.
+ *
+ * The rule is recorded per die on `env.critRules`, so dice that explode and
+ * reroll mint *after* the crit node has run inherit it from the die they
+ * descended from. `cs`/`cf` therefore covers the whole pool wherever it sits
+ * in the postfix chain — `1d6cs<2!` and `1d6!cs<2` agree. Two things stay
+ * outside that: compound explode, which mints no die and so keeps the flags
+ * its accumulated `result` had when the crit node ran, and `minN`/`maxN`,
+ * which rewrites `result` under an explicit threshold's feet.
+ *
  * 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
@@ -18,42 +52,90 @@
  */
 
 import type { DieResult, ResolvedCritThreshold } from '../../types.js';
+import type { CritRule, EvalEnv } from '../env.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
- * 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.
+ * die's `critical` and `fumble` flags in place. Writing `natural` for
+ * `initialResult ?? result`, a die matches `'default'` on the success side
+ * when `natural === sides && sides > 1`, and on the fail side when
+ * `natural === 1 && sides > 1`. Meta dice are skipped.
+ *
+ * Also records the rule against every die it touched, so later explode and
+ * reroll dice can inherit it via {@link inheritCritRule}.
  */
 export function applyCritThresholds(
   dice: DieResult[],
   successThresholds: ResolvedCritThreshold[],
   failThresholds: ResolvedCritThreshold[],
+  env: EvalEnv,
 ): void {
+  const rule: CritRule = { success: successThresholds, fail: failThresholds };
+  env.critRules ??= new WeakMap();
+  const rules = env.critRules;
+
   for (const die of dice) {
     if (die.modifiers.includes('meta')) continue;
+    if (env.hasVersusDc && isVersusDc(die)) continue;
 
-    die.critical = successThresholds.some((t) => matchesCrit(t, die));
-    die.fumble = failThresholds.some((t) => matchesFumble(t, die));
+    applyCritRule(die, rule, die.initialResult ?? die.result);
+    rules.set(die, rule);
   }
 }
 
-function matchesCrit(threshold: ResolvedCritThreshold, die: DieResult): boolean {
+/**
+ * Judges one die by a recorded rule, overwriting both flags. A side always
+ * carries at least `'default'` — `evalCritThreshold` fills the side the user
+ * left out — so neither flag is silently left untouched. `natural` is the face
+ * the `'default'` sentinel reads; an explicit threshold always reads `result`.
+ */
+function applyCritRule(die: DieResult, rule: CritRule, natural: number): void {
+  die.critical = rule.success.some((t) => matchesCrit(t, die, natural));
+  die.fumble = rule.fail.some((t) => matchesFumble(t, die, natural));
+}
+
+/**
+ * Passes the crit rule recorded for `parent` down to a die minted from it,
+ * judging the child by that rule and recording it so a further explode or
+ * reroll inherits it in turn. No-op when no `cs`/`cf` governs `parent`, which
+ * leaves the `createDieResult` default rule in place.
+ *
+ * `natural` is the face the `'default'` sentinel reads, defaulting to the
+ * child's own. Penetrating explode passes its raw roll — see the module note.
+ *
+ * ! Call this only once the child's final `result` is stored — an explicit
+ * ! threshold is a predicate over `result`, so a penetrating die is judged by
+ * ! its decremented value, matching `1d6!pcs<2`.
+ */
+export function inheritCritRule(
+  env: EvalEnv,
+  parent: DieResult,
+  child: DieResult,
+  natural = child.initialResult ?? child.result,
+): void {
+  const rules = env.critRules;
+  if (rules === undefined) return;
+
+  const rule = rules.get(parent);
+  if (rule === undefined) return;
+
+  applyCritRule(child, rule, natural);
+  rules.set(child, rule);
+}
+
+function matchesCrit(threshold: ResolvedCritThreshold, die: DieResult, natural: number): boolean {
   if (threshold === 'default') {
-    return die.result === die.sides && die.sides > 1;
+    return natural === die.sides && die.sides > 1;
   }
   return matchesCondition(die.result, threshold.operator, threshold.value);
 }
 
-function matchesFumble(threshold: ResolvedCritThreshold, die: DieResult): boolean {
+function matchesFumble(threshold: ResolvedCritThreshold, die: DieResult, natural: number): boolean {
   if (threshold === 'default') {
-    // ? Mirrors `createDieResult` — a d1 always rolls 1, never a fumble.
-    return die.result === 1 && die.sides > 1;
+    // Mirrors `createDieResult` — a d1 always rolls 1, never a fumble.
+    return natural === 1 && die.sides > 1;
   }
   return matchesCondition(die.result, threshold.operator, threshold.value);
 }

package/src/evaluator/modifiers/die-bound.ts

@@ -0,0 +1,48 @@
+/**
+ * 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. The tag is written at most once, so a chain of
+ * same-kind bounds (`4d6min3min4`) leaves a die carrying a single `'min'`.
+ *
+ * `critical` / `fumble` keep reflecting the natural face — a clamped 1 is
+ * still a fumble, matching the raw-face crit semantics used everywhere else.
+ * A following bare `cs`/`cf` agrees; a following *explicit* threshold
+ * (`4d6min5cs>4`) is a predicate over the clamped value and overrides it.
+ * 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,
+  hasVersusDc: boolean,
+): void {
+  for (const die of dice) {
+    if (die.modifiers.includes('meta')) continue;
+    if (hasVersusDc && 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;
+    if (!die.modifiers.includes(bound)) die.modifiers.push(bound);
+  }
+}

package/src/evaluator/modifiers/explode.ts

@@ -8,12 +8,23 @@
  * @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 { inheritCritRule } from './crit-threshold.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 +63,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);
 }
 
@@ -81,45 +85,52 @@ function explodeLimitError(maxIterations: number): EvaluatorError {
  * 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 {
+function canExplode(die: DieResult, hasVersusDc: boolean): boolean {
+  if (hasVersusDc && 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.
+ * An inherited `cs`/`cf` keeps that: it is applied after `storeResult`, so an
+ * explicit threshold reads the stored value, while the raw roll is handed over
+ * for the `'default'` sentinel to read.
  */
-export function applyStandardExplode(
+function applyAppendingExplode(
   pool: DieResult[],
   shouldExplode: ShouldExplode,
   rng: RNG,
   env: EvalEnv,
+  storeResult: (raw: number) => number,
 ): DieResult[] {
   const result: DieResult[] = [];
 
   for (const original of pool) {
     result.push(original);
-    if (!canExplode(original)) continue;
+    if (!canExplode(original, env.hasVersusDc)) 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);
+      inheritCritRule(env, original, die, raw);
+      result.push(die);
+      lastRaw = raw;
       iterations += 1;
     }
   }
@@ -127,6 +138,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
@@ -143,7 +177,7 @@ export function applyCompoundExplode(
   env: EvalEnv,
 ): DieResult[] {
   for (const original of pool) {
-    if (!canExplode(original)) continue;
+    if (!canExplode(original, env.hasVersusDc)) continue;
 
     const sides = original.sides;
     let accumulated = original.result;
@@ -164,9 +198,10 @@ export function applyCompoundExplode(
 
     if (!exploded) continue;
 
-    // ? `critical` and `fumble` keep referring to the original triggering
-    //   roll — after compounding the `result` is a sum.
-    original.initialResult = original.result;
+    // `critical` and `fumble` keep referring to the original triggering
+    // roll — after compounding the `result` is a sum. First writer wins, so
+    // a preceding `minN`/`maxN` clamp keeps its record of the raw face.
+    original.initialResult ??= original.result;
     original.result = accumulated;
     if (!original.modifiers.includes('exploded')) {
       original.modifiers = [...original.modifiers, 'exploded'];
@@ -179,7 +214,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 +223,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,78 @@
+/**
+ * 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.
+ *
+ * ! Call this behind the shared `hasVersusDc` env flag, never bare. Unguarded
+ * ! inside a per-die loop it cost 11-38% on notation that cannot carry the tag
+ * ! (#281); the flag is `false` until a `vs` has actually tagged something.
+ */
+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',
+];
+
+/**
+ * {@link SELECTION_AND_TALLY_FLAGS} plus `'meta'`, for a meta context merging
+ * into a parent. Meta operands nest (`((1d2)d4)d6`), so a die passes through
+ * the merge once per level and the tag must be rebuilt, not appended.
+ */
+export const META_MERGE_FLAGS: readonly DieModifier[] = [
+  'kept',
+  'dropped',
+  'success',
+  'failure',
+  'meta',
+];
+
+/** 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];
+}