roll-parser 2.3.2 → 3.0.0-beta.0

package/dist/parser/parser.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Pratt parser for dice notation.
+ *
+ * @module parser/parser
+ */
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import { type Token } from '../lexer/tokens.js';
+import type { ComparePoint } from '../types.js';
+import type { ASTNode } from './ast.js';
+/**
+ * Error thrown when the parser encounters invalid syntax.
+ */
+export declare class ParseError extends RollParserError {
+    readonly position: number;
+    readonly token: Token | undefined;
+    constructor(message: string, code: RollParserErrorCode, position: number, token?: Token);
+}
+/**
+ * Pratt parser for dice notation.
+ *
+ * Uses binding power (precedence) to handle operator associativity and
+ * precedence without left recursion issues.
+ */
+export declare class Parser {
+    private readonly tokens;
+    private pos;
+    private depth;
+    constructor(tokens: Token[]);
+    /**
+     * Parse the token stream into an AST.
+     */
+    parse(): ASTNode;
+    /**
+     * Parse an expression with minimum binding power.
+     */
+    private parseExpression;
+    /**
+     * NUD - Null Denotation.
+     * Handles tokens that appear at the start of an expression (prefix position).
+     */
+    private parseNud;
+    /**
+     * LED - Left Denotation.
+     * Handles tokens that appear between expressions (infix/postfix position).
+     */
+    private parseLed;
+    /**
+     * Zero-width span for synthetic nodes (implicit counts, `d%` sides) that
+     * have no source text of their own — anchored at the governing token.
+     */
+    private static syntheticLiteral;
+    private parseLiteral;
+    private parseUnaryMinus;
+    private parsePrefixDice;
+    private parseInfixDice;
+    private parsePrefixDicePercent;
+    private parseInfixDicePercent;
+    private parsePrefixFateDice;
+    private parseInfixFateDice;
+    private parseGrouped;
+    private parseGroup;
+    private parseVariable;
+    private parseFunctionCall;
+    private parseBinaryOp;
+    /**
+     * Rejects a dice token whose count operand is itself a bare (unparenthesized)
+     * dice expression. `4d6d1` would otherwise silently parse as `(4d6)d1` —
+     * roll 4d6, then use the result as a count of d1 dice — which is almost
+     * never intended: every major dice dialect reads `4d6d1` as "drop lowest 1".
+     * Both meanings stay reachable through explicit forms: `4d6dl1` to drop,
+     * `(4d6)d1` for nested dice.
+     */
+    private rejectBareDiceChain;
+    private rejectSuccessCountTarget;
+    /**
+     * Rejects `GroupNode` (or a wrapper-cloaked group) as the target of `token`.
+     * Explode, reroll, and crit-threshold wrap bare dice pools only — a group
+     * is a container of sub-expressions, so these modifiers have no defined
+     * semantics. Walks `Grouped`/`Modifier`/`Sort`/`CritThreshold` so wrappers
+     * cannot smuggle a group past the check (`{1d6}kh1cs>5`, `({1d6})!`,
+     * `{1d6}scs>5` all reject the same as `{1d6}!`/`{1d6}cs>5`).
+     *
+     * `singleSubRollPasses` opts the caller into the Stage 3 single-sub-roll
+     * passthrough rule (STAGE3.md "Group Semantics: Single vs Multi Sub-Roll"):
+     * a `Group` with one expression is the user's explicit flat-pool escape
+     * hatch and is equivalent to its unwrapped form. Currently only
+     * `parseCritThreshold` opts in — explode/reroll keep the strict reject so
+     * existing notation contracts don't shift.
+     */
+    private rejectGroupTarget;
+    private rejectVersusTarget;
+    private parseModifier;
+    private parseExplode;
+    private parseReroll;
+    private parseSort;
+    private parseCritThreshold;
+    private parseSuccessCount;
+    private parseVersus;
+    /**
+     * Checks whether the next token is a comparison operator.
+     */
+    isComparePointAhead(): boolean;
+    /**
+     * Parses a comparison operator followed by a value expression.
+     * Called by modifier parsers (explode, reroll, success counting).
+     *
+     * The threshold value is parsed at `BP.DICE_LEFT`, which binds tighter than
+     * arithmetic. This keeps the comparison bound to the dice pool on the left
+     * rather than letting arithmetic to the right be consumed into the
+     * threshold. As a consequence, `1d6>=5+2` parses as `(1d6>=5)+2` with
+     * threshold `5` — not `7`. Computed thresholds require parens:
+     * `1d6>=(5+2)`. Same binding applies to `parseSuccessCount` below.
+     *
+     * @returns A ComparePoint with the operator and value AST node
+     * @throws {ParseError} If the next token is not a comparison operator
+     */
+    parseComparePoint(): ComparePoint;
+    private getCompareOp;
+    private getOperatorSymbol;
+    private getLeftBp;
+    private getRightBp;
+    private peek;
+    private advance;
+    private expect;
+    private hasTokens;
+}
+/**
+ * Parse a dice notation string into an AST.
+ *
+ * @param notation - The dice notation to parse
+ * @returns The root AST node
+ * @throws {LexerError} If the input contains invalid characters
+ * @throws {ParseError} If the input has invalid syntax
+ *
+ * @example
+ * ```typescript
+ * const ast = parse('2d6+3');
+ * // { type: 'BinaryOp', operator: '+',
+ * //   left: { type: 'Dice', count: 2, sides: 6 },
+ * //   right: { type: 'Literal', value: 3 } }
+ * ```
+ */
+export declare function parse(notation: string): ASTNode;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,OAAO,EAkBR,MAAM,UAAU,CAAC;AAYlB;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAMxF;AAwED;;;;;GAKG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;gBAEN,MAAM,EAAE,KAAK,EAAE;IAI3B;;OAEG;IACH,KAAK,IAAI,OAAO;IAqBhB;;OAEG;IACH,OAAO,CAAC,eAAe;IA8BvB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA4ChB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAgEhB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAI/B,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,qBAAqB;IAc7B,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,UAAU;IA4BlB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,iBAAiB;IA0DzB,OAAO,CAAC,aAAa;IAmBrB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,wBAAwB;IAgBhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,kBAAkB;IAoC1B,OAAO,CAAC,aAAa;IAqDrB,OAAO,CAAC,YAAY;IA+DpB,OAAO,CAAC,WAAW;IAyCnB,OAAO,CAAC,SAAS;IAgDjB,OAAO,CAAC,kBAAkB;IA+E1B,OAAO,CAAC,iBAAiB;IA8CzB,OAAO,CAAC,WAAW;IA6BnB;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAW9B;;;;;;;;;;;;;OAaG;IACH,iBAAiB,IAAI,YAAY;IAajC,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,SAAS;IA2DjB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;IAed,OAAO,CAAC,SAAS;CAGlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI/C"}

package/dist/rng/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * RNG module - Seedable random number generation.
+ *
+ * @module rng
+ */
+export type { RNG } from './types.js';
+export { SeededRNG } from './seeded.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/rng/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rng/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/rng/mock.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Mock RNG for deterministic testing.
+ *
+ * @module rng/mock
+ */
+import type { RNG } from './types.js';
+/**
+ * Error thrown when MockRNG exhausts its predefined values.
+ *
+ * This is intentional behavior to catch incorrect roll counts in tests.
+ * If you see this error, your test is consuming more random values than expected.
+ */
+export declare class MockRNGExhaustedError extends Error {
+    readonly consumed: number;
+    constructor(consumed: number);
+}
+/**
+ * Creates a mock RNG that returns predefined values in sequence.
+ *
+ * IMPORTANT: Throws MockRNGExhaustedError when all values are consumed.
+ * This behavior catches incorrect roll counts in tests - it never wraps around.
+ *
+ * @param values - Array of values to return (dice results for nextInt, floats for next)
+ * @returns RNG instance returning predefined values
+ *
+ * @example
+ * ```typescript
+ * const rng = createMockRng([4, 2, 6]);
+ * rng.nextInt(1, 6);  // Returns 4
+ * rng.nextInt(1, 6);  // Returns 2
+ * rng.nextInt(1, 6);  // Returns 6
+ * rng.nextInt(1, 6);  // Throws MockRNGExhaustedError
+ * ```
+ */
+export declare function createMockRng(values: number[]): RNG;
+//# sourceMappingURL=mock.d.ts.map

package/dist/rng/mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/rng/mock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAsBnD"}

package/dist/rng/seeded.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Seedable RNG using xorshift128 algorithm.
+ *
+ * @module rng/seeded
+ */
+import type { RNG } from './types.js';
+/**
+ * Seedable pseudo-random number generator using xorshift128.
+ *
+ * Produces reproducible sequences from identical seeds.
+ * Period: 2^128 - 1
+ *
+ * @example
+ * ```typescript
+ * // Same seed = same sequence
+ * const rng1 = new SeededRNG('test-seed');
+ * const rng2 = new SeededRNG('test-seed');
+ * rng1.nextInt(1, 6) === rng2.nextInt(1, 6); // true
+ * ```
+ */
+export declare class SeededRNG implements RNG {
+    private s0;
+    private s1;
+    private s2;
+    private s3;
+    constructor(seed?: string | number);
+    private initState;
+    private hashString;
+    private nextUint32;
+    next(): number;
+    nextInt(min: number, max: number): number;
+    /**
+     * Unbiased sampling in `[0, range)` for ranges above 2^32, built from two
+     * uint32 draws combined into a 53-bit integer (the largest width JS numbers
+     * represent exactly). Ranges beyond 2^53 cannot be sampled without bias —
+     * throw instead of silently degrading.
+     */
+    private nextBoundedWide;
+}
+//# sourceMappingURL=seeded.d.ts.map

package/dist/rng/seeded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeded.d.ts","sourceRoot":"","sources":["../../src/rng/seeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,GAAG;IACnC,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAelC,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;IAgBlB,IAAI,IAAI,MAAM;IAKd,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IA6BzC;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAiBxB"}

package/dist/rng/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Random Number Generator interface.
+ *
+ * All dice rolling MUST use this interface - never use Math.random() directly.
+ *
+ * @module rng/types
+ */
+/**
+ * Random Number Generator interface for dice rolling.
+ */
+export type RNG = {
+    /**
+     * Returns a random floating-point number in the range [0, 1).
+     */
+    next(): number;
+    /**
+     * Returns a random integer in the inclusive range [min, max].
+     *
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (inclusive)
+     */
+    nextInt(min: number, max: number): number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/rng/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rng/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG;IAChB;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3C,CAAC"}

package/dist/roll.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Main public API for rolling dice expressions.
+ *
+ * @module roll
+ */
+import type { RNG } from './rng/types.js';
+import type { RollResult } from './types.js';
+/**
+ * Options for the roll function.
+ */
+export type RollOptions = {
+    /** Custom RNG instance (takes precedence over seed) */
+    rng?: RNG;
+    /** Seed for deterministic rolls (ignored if rng provided) */
+    seed?: string | number;
+    /** Maximum total dice allowed per evaluation (default: 10,000) */
+    maxDice?: number;
+    /** Maximum explosion iterations allowed per die (default: 1,000) */
+    maxExplodeIterations?: number;
+    /** Maximum reroll iterations allowed per die (default: 1,000) */
+    maxRerollIterations?: number;
+    /** Variable context for `@name` / `@{name}` references (default: empty) */
+    context?: Record<string, number>;
+    /** Behavior when a referenced variable is missing from context (default: 'throw') */
+    onMissingVariable?: 'throw' | 'zero';
+};
+/**
+ * Parses and evaluates a dice notation string.
+ *
+ * @param notation - Dice notation (e.g., "2d6+3", "4d6kh3")
+ * @param options - Optional configuration (RNG or seed)
+ * @returns Complete roll result with total and metadata
+ *
+ * @example
+ * ```typescript
+ * // Random roll
+ * const result = roll('2d6+3');
+ * console.log(result.total); // 5-15
+ *
+ * // Seeded for reproducibility
+ * const r1 = roll('4d6', { seed: 'test' });
+ * const r2 = roll('4d6', { seed: 'test' });
+ * r1.total === r2.total; // true
+ *
+ * // Custom RNG for testing
+ * const result = roll('1d20', { rng: createMockRng([15]) });
+ * result.total; // 15
+ * ```
+ */
+export declare function roll(notation: string, options?: RollOptions): RollResult;
+//# sourceMappingURL=roll.d.ts.map

package/dist/roll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../src/roll.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAM9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,uDAAuD;IACvD,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAiB5E"}

package/dist/testing.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Test utilities for roll-parser consumers.
+ *
+ * Import from `roll-parser/testing` for deterministic dice testing.
+ *
+ * @module testing
+ */
+import { MockRNGExhaustedError as _MockRNGExhaustedError, createMockRng as _createMockRng } from './rng/mock.js';
+export declare const createMockRng: typeof _createMockRng;
+export declare const MockRNGExhaustedError: typeof _MockRNGExhaustedError;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,qBAAqB,IAAI,sBAAsB,EAC/C,aAAa,IAAI,cAAc,EAChC,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,aAAa,uBAAiB,CAAC;AAC5C,eAAO,MAAM,qBAAqB,+BAAyB,CAAC"}

package/dist/testing.js

@@ -0,0 +1,41 @@
+// src/rng/mock.ts
+class MockRNGExhaustedError extends Error {
+  consumed;
+  constructor(consumed) {
+    super(`MockRNG exhausted: consumed ${consumed} values, no more available`);
+    this.name = "MockRNGExhaustedError";
+    this.consumed = consumed;
+  }
+}
+function createMockRng(values) {
+  let index = 0;
+  const getNext = () => {
+    const value = values[index];
+    if (value === undefined) {
+      throw new MockRNGExhaustedError(index);
+    }
+    index++;
+    return value;
+  };
+  return {
+    next: getNext,
+    nextInt: (min, max) => {
+      const value = getNext();
+      if (value < min || value > max) {
+        throw new RangeError(`MockRNG value ${value} is out of bounds [${min}, ${max}]`);
+      }
+      return value;
+    }
+  };
+}
+
+// src/testing.ts
+var createMockRng2 = createMockRng;
+var MockRNGExhaustedError2 = MockRNGExhaustedError;
+export {
+  createMockRng2 as createMockRng,
+  MockRNGExhaustedError2 as MockRNGExhaustedError
+};
+
+//# debugId=916ECEA68894E64864756E2164756E21
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/rng/mock.ts", "../src/testing.ts"],
+  "sourcesContent": [
+    "/**\n * Mock RNG for deterministic testing.\n *\n * @module rng/mock\n */\n\nimport type { RNG } from './types.js';\n\n/**\n * Error thrown when MockRNG exhausts its predefined values.\n *\n * This is intentional behavior to catch incorrect roll counts in tests.\n * If you see this error, your test is consuming more random values than expected.\n */\nexport class MockRNGExhaustedError extends Error {\n  readonly consumed: number;\n\n  constructor(consumed: number) {\n    super(`MockRNG exhausted: consumed ${consumed} values, no more available`);\n    this.name = 'MockRNGExhaustedError';\n    this.consumed = consumed;\n  }\n}\n\n/**\n * Creates a mock RNG that returns predefined values in sequence.\n *\n * IMPORTANT: Throws MockRNGExhaustedError when all values are consumed.\n * This behavior catches incorrect roll counts in tests - it never wraps around.\n *\n * @param values - Array of values to return (dice results for nextInt, floats for next)\n * @returns RNG instance returning predefined values\n *\n * @example\n * ```typescript\n * const rng = createMockRng([4, 2, 6]);\n * rng.nextInt(1, 6);  // Returns 4\n * rng.nextInt(1, 6);  // Returns 2\n * rng.nextInt(1, 6);  // Returns 6\n * rng.nextInt(1, 6);  // Throws MockRNGExhaustedError\n * ```\n */\nexport function createMockRng(values: number[]): RNG {\n  let index = 0;\n\n  const getNext = (): number => {\n    const value = values[index];\n    if (value === undefined) {\n      throw new MockRNGExhaustedError(index);\n    }\n    index++;\n    return value;\n  };\n\n  return {\n    next: getNext,\n    nextInt: (min: number, max: number): number => {\n      const value = getNext();\n      if (value < min || value > max) {\n        throw new RangeError(`MockRNG value ${value} is out of bounds [${min}, ${max}]`);\n      }\n      return value;\n    },\n  };\n}\n",
+    "/**\n * Test utilities for roll-parser consumers.\n *\n * Import from `roll-parser/testing` for deterministic dice testing.\n *\n * @module testing\n */\n\n// Direct value exports force the bundler to inline the code\nimport {\n  MockRNGExhaustedError as _MockRNGExhaustedError,\n  createMockRng as _createMockRng,\n} from './rng/mock.js';\n\nexport const createMockRng = _createMockRng;\nexport const MockRNGExhaustedError = _MockRNGExhaustedError;\n"
+  ],
+  "mappings": ";AAcO,MAAM,8BAA8B,MAAM;AAAA,EACtC;AAAA,EAET,WAAW,CAAC,UAAkB;AAAA,IAC5B,MAAM,+BAA+B,oCAAoC;AAAA,IACzE,KAAK,OAAO;AAAA,IACZ,KAAK,WAAW;AAAA;AAEpB;AAoBO,SAAS,aAAa,CAAC,QAAuB;AAAA,EACnD,IAAI,QAAQ;AAAA,EAEZ,MAAM,UAAU,MAAc;AAAA,IAC5B,MAAM,QAAQ,OAAO;AAAA,IACrB,IAAI,UAAU,WAAW;AAAA,MACvB,MAAM,IAAI,sBAAsB,KAAK;AAAA,IACvC;AAAA,IACA;AAAA,IACA,OAAO;AAAA;AAAA,EAGT,OAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS,CAAC,KAAa,QAAwB;AAAA,MAC7C,MAAM,QAAQ,QAAQ;AAAA,MACtB,IAAI,QAAQ,OAAO,QAAQ,KAAK;AAAA,QAC9B,MAAM,IAAI,WAAW,iBAAiB,2BAA2B,QAAQ,MAAM;AAAA,MACjF;AAAA,MACA,OAAO;AAAA;AAAA,EAEX;AAAA;;;ACjDK,IAAM,iBAAgB;AACtB,IAAM,yBAAwB;",
+  "debugId": "916ECEA68894E64864756E2164756E21",
+  "names": []
+}

package/dist/types.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Shared type definitions for roll results and comparison primitives.
+ *
+ * @module types
+ */
+import type { ASTNode } from './parser/ast.js';
+/**
+ * Comparison operator for compare points.
+ */
+export type CompareOp = '>' | '>=' | '<' | '<=' | '=';
+/**
+ * A comparison threshold used by exploding dice, reroll, and success counting.
+ *
+ * The value is an ASTNode to support computed thresholds (e.g., `>=ceil(5)`),
+ * matching the pattern used by DiceNode.count and DiceNode.sides.
+ */
+export type ComparePoint = {
+    operator: CompareOp;
+    value: ASTNode;
+};
+/**
+ * A ComparePoint whose value has been evaluated to a number. Used in
+ * `RollPart` where meta-expressions are already resolved.
+ */
+export type ResolvedComparePoint = {
+    operator: CompareOp;
+    value: number;
+};
+/**
+ * A resolved crit threshold — `'default'` means the per-die default rule
+ * (`result === sides` for critical, `result === 1` for fumble).
+ */
+export type ResolvedCritThreshold = ResolvedComparePoint | 'default';
+/**
+ * Modifier flags applied to individual die results.
+ */
+export type DieModifier = 'dropped' | 'kept' | 'exploded' | 'rerolled' | 'success' | 'failure' | 'meta';
+/**
+ * PF2e Degree of Success. Produced by the `vs` operator when comparing a
+ * roll against a Difficulty Class. Ordering is significant — natural 20
+ * upgrades one step and natural 1 downgrades one step.
+ */
+export declare enum DegreeOfSuccess {
+    CriticalFailure = 0,
+    Failure = 1,
+    Success = 2,
+    CriticalSuccess = 3
+}
+/**
+ * Individual die roll result with metadata.
+ */
+export type DieResult = {
+    /**
+     * Number of sides on the die. Normal dice use `sides >= 1`. Fate/Fudge
+     * dice use `sides = 0` as a sentinel — they have no configurable sides
+     * and always produce results in {-1, 0, +1}.
+     */
+    sides: number;
+    /** The rolled value */
+    result: number;
+    /**
+     * Raw first roll before any mutation (e.g., compound-explode accumulation).
+     * Only populated when `result` has been overwritten with a computed value.
+     * Consumers that need the original face (nat-20 / nat-1 detection) should
+     * read `initialResult ?? result`.
+     */
+    initialResult?: number;
+    /** Modifiers applied to this die */
+    modifiers: DieModifier[];
+    /** True if rolled the maximum value (always false for Fate dice) */
+    critical: boolean;
+    /** True if rolled 1 (always false for Fate dice) */
+    fumble: boolean;
+};
+/**
+ * Per-spec keep/drop entry inside a flattened modifier chain. Counts are
+ * resolved at evaluation time (meta-expressions like `kh(1d2)` become the
+ * rolled number).
+ */
+export type ModifierSpec = {
+    kind: 'keep' | 'drop';
+    selector: 'highest' | 'lowest';
+    count: number;
+};
+/**
+ * Fields shared by every RollPart variant. `start`/`end` mirror the source
+ * span of the AST node the part was evaluated from — present whenever the
+ * AST came from `parse()`, absent on hand-built ASTs.
+ */
+type RollPartBase = {
+    /** Sub-total this part contributed to its parent. */
+    total: number;
+    start?: number;
+    end?: number;
+};
+/**
+ * Structured breakdown of an evaluated expression, mirroring the AST 1:1 —
+ * every ASTNode produces exactly one RollPart. Discriminants are lowercase
+ * camelCase to distinguish evaluation-tree types from `ASTNode.type`
+ * (PascalCase) at a glance.
+ *
+ * Invariants:
+ * - `RollResult.parts.total === RollResult.total`.
+ * - `successCount.total === successes - failures`.
+ * - `literal.total === value` and `variable.total === value`.
+ * - Each part's `rolls[]` shares `DieResult` references with
+ *   `RollResult.rolls[]`; both reflect post-evaluation state (explode
+ *   accumulation, reroll flags, keep/drop flags). No deep clone.
+ *
+ * Meta-expression sub-trees (`4d6kh(1d2)`, `(1+1)d6` counts/sides, computed
+ * thresholds) are not surfaced as nested parts — their resolved numbers
+ * appear in the owning part, and their dice are inspectable in
+ * `RollResult.rolls` via the `'meta'` modifier tag.
+ */
+export type RollPart = (RollPartBase & {
+    type: 'literal';
+    value: number;
+}) | (RollPartBase & {
+    type: 'variable';
+    name: string;
+    value: number;
+}) | (RollPartBase & {
+    type: 'dice';
+    count: number;
+    sides: number;
+    rolls: DieResult[];
+}) | (RollPartBase & {
+    type: 'fateDice';
+    count: number;
+    rolls: DieResult[];
+}) | (RollPartBase & {
+    type: 'grouped';
+    inner: RollPart;
+}) | (RollPartBase & {
+    type: 'binaryOp';
+    operator: '+' | '-' | '*' | '/' | '%' | '**';
+    left: RollPart;
+    right: RollPart;
+}) | (RollPartBase & {
+    type: 'unaryOp';
+    operator: '-';
+    operand: RollPart;
+}) | (RollPartBase & {
+    type: 'modifier';
+    specs: ModifierSpec[];
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'explode';
+    variant: 'standard' | 'compound' | 'penetrating';
+    threshold?: ResolvedComparePoint;
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'reroll';
+    once: boolean;
+    condition: ResolvedComparePoint;
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'successCount';
+    threshold: ResolvedComparePoint;
+    failThreshold?: ResolvedComparePoint;
+    target: RollPart;
+    successes: number;
+    failures: number;
+}) | (RollPartBase & {
+    type: 'versus';
+    roll: RollPart;
+    dc: RollPart;
+    degree: DegreeOfSuccess;
+}) | (RollPartBase & {
+    type: 'functionCall';
+    name: string;
+    args: RollPart[];
+}) | (RollPartBase & {
+    type: 'group';
+    parts: RollPart[];
+    keptIndices?: number[];
+}) | (RollPartBase & {
+    type: 'sort';
+    order: 'ascending' | 'descending';
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'critThreshold';
+    successThresholds: ResolvedCritThreshold[];
+    failThresholds: ResolvedCritThreshold[];
+    target: RollPart;
+});
+/** Convenience alias for consumers writing exhaustive switches. */
+export type RollPartType = RollPart['type'];
+/**
+ * Complete roll result with all metadata.
+ */
+export type RollResult = {
+    /** Final computed total */
+    total: number;
+    /** Original input notation */
+    notation: string;
+    /** Normalized expression */
+    expression: string;
+    /** Rendered result with individual rolls shown */
+    rendered: string;
+    /** All individual die results */
+    rolls: DieResult[];
+    /** Structured breakdown of the evaluated expression, mirroring the AST 1:1. */
+    parts: RollPart;
+    /**
+     * Number of dice tagged as success across the whole expression. Present
+     * only when a success-counting modifier was used. Independent of `total` —
+     * arithmetic on top of a success count (e.g. `5d6>=5 * 2`) affects `total`
+     * but not `successes`.
+     */
+    successes?: number;
+    /**
+     * Number of dice tagged as failure across the whole expression. Present
+     * only when a success-counting modifier with a fail threshold was used.
+     */
+    failures?: number;
+    /**
+     * PF2e Degree of Success. Present only when the expression used the `vs`
+     * operator at the top level (e.g. `1d20+10 vs 25`).
+     */
+    degree?: DegreeOfSuccess;
+    /**
+     * Natural d20 value used for PF2e upgrade/downgrade — present only when
+     * exactly one kept d20 was rolled on the roll side of a `vs` expression.
+     */
+    natural?: number;
+};
+/**
+ * Options for the evaluate function.
+ */
+export type EvaluateOptions = {
+    /** Original notation string (for result metadata) */
+    notation?: string;
+    /** Maximum total dice allowed per evaluation (default: 10,000) */
+    maxDice?: number;
+    /** Maximum explosion iterations allowed per die (default: 1,000) */
+    maxExplodeIterations?: number;
+    /** Maximum reroll iterations allowed per die (default: 1,000) */
+    maxRerollIterations?: number;
+    /** Variable context for `@name` / `@{name}` references (default: empty) */
+    context?: Record<string, number>;
+    /** Behavior when a referenced variable is missing from context (default: 'throw') */
+    onMissingVariable?: 'throw' | 'zero';
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}