roll-parser 3.0.0-beta.0 → 3.1.0

package/dist/evaluator/env.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Per-evaluation shared environment.
+ *
+ * Lives in its own module so the modifier implementations under
+ * `./modifiers/*` can type their `env` parameter without importing
+ * `./evaluator.js`, which imports them back.
+ *
+ * @module evaluator/env
+ */
+import type { ASTNode } from '../parser/ast.js';
+import type { DieResult, ResolvedCritThreshold } from '../types.js';
+/**
+ * A resolved `cs`/`cf` pair, recorded per die so that dice minted later by
+ * explode or reroll can be judged by the rule the user declared instead of
+ * the built-in default.
+ */
+export type CritRule = {
+    readonly success: readonly ResolvedCritThreshold[];
+    readonly fail: readonly ResolvedCritThreshold[];
+};
+/**
+ * Per-evaluation shared environment (created once, shared across all branches).
+ *
+ * Exported for use by modifier implementations under `./modifiers/*`. Not part
+ * of the public library API.
+ */
+export type EvalEnv = {
+    readonly maxDice: number;
+    readonly maxExplodeIterations: number;
+    readonly maxRerollIterations: number;
+    totalDiceRolled: number;
+    /**
+     * Set to `true` by `evalSuccessCount`. Propagates through the shared env
+     * so `evaluate()` can include `successes`/`failures` fields even when no
+     * die was tagged (impossible threshold).
+     */
+    hasSuccessCount: boolean;
+    /**
+     * `true` while the evaluator is inside a `VersusNode`'s roll or DC
+     * sub-evaluation. `evalVersus` rejects nesting via this flag — catches
+     * paren-nested versus (`1d20 vs (5 vs 3)`) that slip past the parser's
+     * left-chain check.
+     */
+    insideVersus: boolean;
+    /**
+     * `true` once a `vs` has tagged its DC dice `'dc'`. Lets every pool
+     * operation skip its per-die `isVersusDc` check outright — the tag exists in
+     * a small minority of notation, and the call inside the loop cost 11-38% on
+     * keep/drop, success, and sort notation that can never carry one (#281).
+     *
+     * ! Monotonic: set by `evalVersus`, never cleared. `insideVersus` is not a
+     * ! model for it — that flag resets in a `finally`, and it is false exactly
+     * ! when the tagged DC dice become visible to the enclosing pool.
+     */
+    hasVersusDc: boolean;
+    /**
+     * Crit rule per die, keyed on the `DieResult` object itself. Populated by
+     * `applyCritThresholds`; read by explode and reroll so a die they mint
+     * inherits the rule of the die it descended from.
+     *
+     * Out of band rather than a `DieResult` field because `DieResult` is public
+     * and serialized. `undefined` until the first `cs`/`cf` node — declared here
+     * so the shape stays stable for notation that has none.
+     */
+    critRules: WeakMap<DieResult, CritRule> | undefined;
+    /**
+     * User-supplied variable map for `@name` / `@{name}` references. Always
+     * defined — `evaluate()` defaults to an empty object so lookups can be
+     * branch-free on presence.
+     */
+    readonly context: Readonly<Record<string, number>>;
+    /**
+     * Behavior when a referenced variable is missing from `context`. Always
+     * defined — `evaluate()` defaults to `'throw'`.
+     */
+    readonly onMissingVariable: 'throw' | 'zero';
+};
+/**
+ * Reserves `count` dice against the global `maxDice` budget, throwing
+ * `DICE_LIMIT_EXCEEDED` when the reservation would overshoot.
+ *
+ * Every path that consumes RNG draws for dice charges through here — initial
+ * pools (`evalDice` / `evalFateDice`), explosion continuations, and reroll
+ * replacements — so the limit and its message have one definition.
+ */
+export declare function chargeDice(env: EvalEnv, count: number, nodeType: ASTNode['type']): void;
+/** Single-die shorthand for {@link chargeDice}. */
+export declare function chargeDie(env: EvalEnv, nodeType: ASTNode['type']): void;
+//# sourceMappingURL=env.d.ts.map

package/dist/evaluator/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/evaluator/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;;;;;OASG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CASvF;AAED,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAEvE"}

package/dist/evaluator/env.js

@@ -0,0 +1,11 @@
+import { EvaluatorError } from '../errors.js';
+export function chargeDice(env, count, nodeType) {
+    if (env.totalDiceRolled + count > env.maxDice) {
+        throw new EvaluatorError(`Total dice count ${env.totalDiceRolled + count} exceeds limit of ${env.maxDice}`, 'DICE_LIMIT_EXCEEDED', nodeType);
+    }
+    env.totalDiceRolled += count;
+}
+export function chargeDie(env, nodeType) {
+    chargeDice(env, 1, nodeType);
+}
+//# sourceMappingURL=env.js.map

package/dist/evaluator/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/evaluator/env.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAgF9C,MAAM,UAAU,UAAU,CAAC,GAAY,EAAE,KAAa,EAAE,QAAyB;IAC/E,IAAI,GAAG,CAAC,eAAe,GAAG,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;QAC9C,MAAM,IAAI,cAAc,CACtB,oBAAoB,GAAG,CAAC,eAAe,GAAG,KAAK,qBAAqB,GAAG,CAAC,OAAO,EAAE,EACjF,qBAAqB,EACrB,QAAQ,CACT,CAAC;IACJ,CAAC;IACD,GAAG,CAAC,eAAe,IAAI,KAAK,CAAC;AAC/B,CAAC;AAGD,MAAM,UAAU,SAAS,CAAC,GAAY,EAAE,QAAyB;IAC/D,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC/B,CAAC"}

package/dist/evaluator/evaluator.d.ts

@@ -3,71 +3,32 @@
  *
  * @module evaluator/evaluator
  */
-import type { RollParserErrorCode } from '../errors.js';
-import { RollParserError } from '../errors.js';
+import { EvaluatorError } from '../errors.js';
 import type { ASTNode } from '../parser/ast.js';
 import type { RNG } from '../rng/types.js';
 import type { DieResult, EvaluateOptions, RollResult } from '../types.js';
 import { DegreeOfSuccess } from '../types.js';
 import { DEFAULT_MAX_EXPLODE_ITERATIONS } from './modifiers/explode.js';
 import { DEFAULT_MAX_REROLL_ITERATIONS } from './modifiers/reroll.js';
+export { EvaluatorError };
 /**
- * Error thrown during AST evaluation.
+ * Default value of `EvaluationOptions.maxDice`: the number of dice a single
+ * evaluation may roll before `DICE_LIMIT_EXCEEDED` is thrown.
+ *
+ * Counted across the whole expression, not per pool, so `6000d6+6000d6`
+ * breaches it. Includes dice rolled by explosions, rerolls, and
+ * meta-expressions.
+ *
+ * @category Limits
  */
-export declare class EvaluatorError extends RollParserError {
-    readonly nodeType: string | undefined;
-    /**
-     * Source span of the tightest AST node that was being evaluated when the
-     * error was thrown — stamped by `evalNode` on the way up, so the innermost
-     * node wins. `undefined` when the AST was built without parser spans.
-     */
-    start: number | undefined;
-    end: number | undefined;
-    constructor(message: string, code: RollParserErrorCode, nodeType?: string);
-}
-/** Default maximum total dice allowed per evaluation. */
 export declare const DEFAULT_MAX_DICE = 10000;
 export { DEFAULT_MAX_EXPLODE_ITERATIONS, DEFAULT_MAX_REROLL_ITERATIONS };
-/**
- * Per-evaluation shared environment (created once, shared across all branches).
- *
- * Exported for use by modifier implementations under `./modifiers/*`. Not part
- * of the public library API.
- */
-export type EvalEnv = {
-    readonly maxDice: number;
-    readonly maxExplodeIterations: number;
-    readonly maxRerollIterations: number;
-    totalDiceRolled: number;
-    /**
-     * Set to `true` by `evalSuccessCount`. Propagates through the shared env
-     * so `evaluate()` can include `successes`/`failures` fields even when no
-     * die was tagged (impossible threshold).
-     */
-    hasSuccessCount: boolean;
-    /**
-     * `true` while the evaluator is inside a `VersusNode`'s roll or DC
-     * sub-evaluation. `evalVersus` rejects nesting via this flag — catches
-     * paren-nested versus (`1d20 vs (5 vs 3)`) that slip past the parser's
-     * left-chain check.
-     */
-    insideVersus: boolean;
-    /**
-     * User-supplied variable map for `@name` / `@{name}` references. Always
-     * defined — `evaluate()` defaults to an empty object so lookups can be
-     * branch-free on presence.
-     */
-    readonly context: Readonly<Record<string, number>>;
-    /**
-     * Behavior when a referenced variable is missing from `context`. Always
-     * defined — `evaluate()` defaults to `'throw'`.
-     */
-    readonly onMissingVariable: 'throw' | 'zero';
-};
 /**
  * Per-branch mutable accumulator for tracking rolls and output during recursion.
  *
- * @internal exported for targeted `mergeMetaRolls` tests only; not a public API.
+ * Module-level export, deliberately absent from `src/index.ts` — the package
+ * surface never mentions it. See {@link mergeMetaRolls} for why the export
+ * exists at all.
  */
 export type EvalContext = {
     rolls: DieResult[];
@@ -86,36 +47,41 @@ export type EvalContext = {
     };
 };
 /**
- * Forwards rolls from a throwaway sub-expression context into the parent
- * audit trail, tagging them as `'meta'` + `'dropped'`. Meta dice are dice
- * rolled to compute parameters (dice count, sides, threshold, modifier
- * count) — they consume RNG and count against `maxDice`, so they must be
- * inspectable. Tagging them `'dropped'` keeps totals correct via
- * `sumKeptDice`; `'meta'` lets renderers hide them and lets callers
- * distinguish them from ordinary pool dice.
+ * Evaluates a parsed AST against an {@link RNG} and returns the roll result.
  *
- * `'success'`/`'failure'` tags are stripped here as defense-in-depth against
- * a SuccessCount leaking into a meta sub-expression (parser rejects all such
- * wrappings; this strip ensures a future parse regression cannot leak tags
- * into the top-level `successes`/`failures` scan).
- */
-/** @internal exported for targeted defense-in-depth tests only. */
-export declare function mergeMetaRolls(parent: EvalContext, source: EvalContext): void;
-/**
- * Evaluates a parsed AST and returns the roll result.
+ * The second half of the pipeline — {@link roll} is `evaluate(parse(...))`.
+ * Call it directly to reuse one AST across many rolls, or to drive a
+ * hand-built AST.
+ *
+ * Unlike `roll`, the RNG is required: `evaluate` never invents a randomness
+ * source, so a caller can never accidentally get an unseeded roll.
  *
- * @param ast - The parsed AST node
- * @param rng - Random number generator to use for dice rolls
- * @param options - Optional evaluation options
- * @returns Complete roll result with total and metadata
+ * @param ast - The AST to evaluate, from {@link parse} or hand-built
+ * @param rng - Randomness source; one `nextInt` call per die
+ * @param options - Evaluation limits plus the original `notation` string,
+ *   which the AST cannot supply
+ * @returns Complete {@link RollResult}
+ * @throws {EvaluatorError} On a limit breach, division by zero, an undefined
+ *   variable, or a non-finite total
+ * @throws {RollParserError} `INVALID_EVALUATION_LIMIT` when a supplied limit is
+ *   not an integer in range — raised before any die is rolled
  *
  * @example
  * ```typescript
+ * import { evaluate, parse } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
  * const ast = parse('2d6+3');
- * const rng = new SeededRNG('test');
- * const result = evaluate(ast, rng);
- * console.log(result.total); // Sum of dice plus 3
+ * const result = evaluate(ast, createMockRng([4, 2]), { notation: '2d6+3' });
+ * result.total; // 9
+ * result.rendered; // '2d6[4, 2] + 3 = 9'
  * ```
+ *
+ * Omitting `notation` falls back to the normalized `expression`, which is
+ * reconstructed from the AST — so `RollResult.notation` is always a string,
+ * just not necessarily the one the user typed.
+ *
+ * @category Core
  */
 export declare function evaluate(ast: ASTNode, rng: RNG, options?: EvaluateOptions): RollResult;
 //# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator/evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EACV,OAAO,EAkBR,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAEV,SAAS,EACT,eAAe,EAGf,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAKL,8BAA8B,EAC/B,MAAM,wBAAwB,CAAC;AAShC,OAAO,EAGL,6BAA6B,EAC9B,MAAM,uBAAuB,CAAC;AAI/B;;GAEG;AACH,qBAAa,cAAe,SAAQ,eAAe;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,CAAC,EAAE,MAAM;CAO1E;AAED,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,cAAc,CAAC,EAAE;QACf,MAAM,EAAE,eAAe,CAAC;QACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AA+FF;;;;;;;;;;;;;GAaG;AACH,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAa7E;AA8pCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,eAAoB,GAAG,UAAU,CAmF1F"}
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiB,cAAc,EAAuC,MAAM,cAAc,CAAC;AAClG,OAAO,KAAK,EACV,OAAO,EAmBR,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAIV,SAAS,EACT,eAAe,EAKf,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK9C,OAAO,EAKL,8BAA8B,EAC/B,MAAM,wBAAwB,CAAC;AAShC,OAAO,EAGL,6BAA6B,EAC9B,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAAE,cAAc,EAAE,CAAC;AAM1B;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAmCvC,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,CAAC;AAMzE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,cAAc,CAAC,EAAE;QACf,MAAM,EAAE,eAAe,CAAC;QACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAogDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,eAAoB,GAAG,UAAU,CA8D1F"}