roll-parser 3.0.0-beta.0 → 3.0.0

package/src/evaluator/modifiers/reroll.ts

@@ -9,49 +9,37 @@
  * @module evaluator/modifiers/reroll
  */
 
+import { EvaluatorError } from '../../errors.js';
 import type { RNG } from '../../rng/types.js';
 import type { CompareOp, DieResult } from '../../types.js';
-import { EvaluatorError, type EvalEnv } from '../evaluator.js';
+import { createDieResult, createFateDieResult } from '../die.js';
+import { chargeDie, type EvalEnv } from '../env.js';
 import { matchesCondition } from './compare.js';
+import { isVersusDc, REROLL_SLOT_FLAGS, rewriteFlags } from './flags.js';
 
-/** Default maximum reroll iterations per die. */
+/**
+ * Default value of `EvaluationOptions.maxRerollIterations`: how many times a
+ * single die may be re-rolled by `r` before `REROLL_LIMIT_EXCEEDED` is
+ * thrown.
+ *
+ * Per die, not per pool — it bounds notations like `1d1r<2`, whose reroll
+ * condition can never stop matching. `ro` re-rolls exactly once and is
+ * unaffected.
+ *
+ * @category Limits
+ */
 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,
-    };
-  }
+  chargeDie(env, 'Reroll');
+
+  if (sides === 0) return createFateDieResult(rng.nextInt(-1, 1), []);
 
-  const result = rng.nextInt(1, sides);
-  return {
-    sides,
-    result,
-    modifiers: [],
-    critical: result === sides && sides > 1,
-    fumble: result === 1 && sides > 1,
-  };
+  return createDieResult(sides, rng.nextInt(1, sides), []);
 }
 
 function rerollLimitError(maxIterations: number): EvaluatorError {
@@ -67,16 +55,7 @@ function rerollLimitError(maxIterations: number): EvaluatorError {
  * 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');
+  return !die.modifiers.includes('dropped') && !isVersusDc(die);
 }
 
 /**
@@ -105,21 +84,21 @@ export function applyRecursiveReroll(
     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.
+    // 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'];
+      current.modifiers = rewriteFlags(current.modifiers, REROLL_SLOT_FLAGS, 'rerolled', 'dropped');
       result.push(current);
 
       current = rollReplacement(current.sides, rng, env);
       iterations += 1;
     }
 
-    current.modifiers = [...stripSlotFlags(current.modifiers), 'kept'];
+    current.modifiers = rewriteFlags(current.modifiers, REROLL_SLOT_FLAGS, 'kept');
     result.push(current);
   }
 
@@ -146,18 +125,18 @@ export function applyRerollOnce(
       continue;
     }
 
-    // ? Mutate flags in place — see `applyRecursiveReroll`.
+    // Mutate flags in place — see `applyRecursiveReroll`.
     if (!matchesCondition(original.result, operator, value)) {
-      original.modifiers = [...stripSlotFlags(original.modifiers), 'kept'];
+      original.modifiers = rewriteFlags(original.modifiers, REROLL_SLOT_FLAGS, 'kept');
       result.push(original);
       continue;
     }
 
-    original.modifiers = [...stripSlotFlags(original.modifiers), 'rerolled', 'dropped'];
+    original.modifiers = rewriteFlags(original.modifiers, REROLL_SLOT_FLAGS, 'rerolled', 'dropped');
     result.push(original);
 
     const replacement = rollReplacement(original.sides, rng, env);
-    replacement.modifiers = [...stripSlotFlags(replacement.modifiers), 'kept'];
+    replacement.modifiers = rewriteFlags(replacement.modifiers, REROLL_SLOT_FLAGS, 'kept');
     result.push(replacement);
   }
 

package/src/evaluator/modifiers/sort.ts

@@ -7,10 +7,15 @@
  * Dropped dice stay in the pool and sort alongside kept dice so readers can
  * see where the dropped value landed in the ordered sequence.
  *
+ * DC dice are the exception: they hold their positions rather than sorting,
+ * so a `vs` comparison's DC faces never appear shuffled into the roll-side
+ * pool they are not a member of.
+ *
  * @module evaluator/modifiers/sort
  */
 
 import type { DieResult } from '../../types.js';
+import { isVersusDc } from './flags.js';
 
 /**
  * Returns a sorted copy of `dice` in the given order, preserving every die's
@@ -26,5 +31,13 @@ export function sortDice(dice: DieResult[], order: 'ascending' | 'descending'):
     order === 'ascending'
       ? (a: DieResult, b: DieResult) => a.result - b.result
       : (a: DieResult, b: DieResult) => b.result - a.result;
-  return [...dice].sort(cmp);
+
+  const sortable = dice.filter((die) => !isVersusDc(die));
+  if (sortable.length === dice.length) return [...dice].sort(cmp);
+
+  // Sort only the pool members, then lay them back into the slots they came
+  // from, leaving every DC die exactly where it was.
+  sortable.sort(cmp);
+  let next = 0;
+  return dice.map((die) => (isVersusDc(die) ? die : (sortable[next++] as DieResult)));
 }

package/src/evaluator/modifiers/success-count.ts

@@ -15,13 +15,9 @@
  * @module evaluator/modifiers/success-count
  */
 
-import type { CompareOp, DieResult } from '../../types.js';
+import type { DieResult, ResolvedComparePoint } from '../../types.js';
 import { matchesCondition } from './compare.js';
-
-export type ResolvedThreshold = {
-  operator: CompareOp;
-  value: number;
-};
+import { isVersusDc } from './flags.js';
 
 export type SuccessCountResult = {
   total: number;
@@ -31,13 +27,14 @@ export type SuccessCountResult = {
 
 export function countSuccesses(
   dice: DieResult[],
-  threshold: ResolvedThreshold,
-  failThreshold?: ResolvedThreshold,
+  threshold: ResolvedComparePoint,
+  failThreshold?: ResolvedComparePoint,
 ): SuccessCountResult {
   let successes = 0;
   let failures = 0;
 
   for (const die of dice) {
+    if (isVersusDc(die)) continue;
     if (die.modifiers.includes('dropped')) continue;
 
     if (matchesCondition(die.result, threshold.operator, threshold.value)) {

package/src/index.ts

@@ -4,31 +4,45 @@
  * @module roll-parser
  */
 
-// * Error hierarchy
-export { RollParserError, isRollParserError } from './errors.js';
-export type { RollParserErrorCode } from './errors.js';
+import { version } from './version.js';
 
-// * Lexer exports
-export { LexerError } from './lexer/lexer.js';
-
-// * Parser exports
-export { parse, ParseError } from './parser/parser.js';
+export type { ErrorSpan, NotationErrorCode, RollParserErrorCode } from './errors.js';
+export {
+  getErrorSpan,
+  isNotationError,
+  isRollParserError,
+  NOTATION_ERROR_CODES,
+  ROLL_PARSER_ERROR_CODES,
+  RollParserError,
+} from './errors.js';
+export {
+  DEFAULT_MAX_DICE,
+  DEFAULT_MAX_EXPLODE_ITERATIONS,
+  DEFAULT_MAX_REROLL_ITERATIONS,
+  EvaluatorError,
+  evaluate,
+} from './evaluator/evaluator.js';
+export { LexerError, lex } from './lexer/lexer.js';
+export type { Token } from './lexer/tokens.js';
+export { TokenType } from './lexer/tokens.js';
 export type {
   ASTNode,
   BinaryOpNode,
+  CritThreshold,
+  CritThresholdNode,
   DiceNode,
-  NodeSpan,
+  DieBoundNode,
   ExplodeNode,
   FateDiceNode,
   FunctionCallNode,
   GroupedNode,
+  GroupNode,
+  KeepDropNode,
   LiteralNode,
-  ModifierNode,
+  NodeSpan,
   RerollNode,
-  SuccessCountNode,
   SortNode,
-  CritThresholdNode,
-  GroupNode,
+  SuccessCountNode,
   UnaryOpNode,
   VariableNode,
   VersusNode,
@@ -37,13 +51,14 @@ export {
   isBinaryOp,
   isCritThreshold,
   isDice,
+  isDieBound,
   isExplode,
   isFateDice,
   isFunctionCall,
   isGroup,
   isGrouped,
+  isKeepDrop,
   isLiteral,
-  isModifier,
   isReroll,
   isSort,
   isSuccessCount,
@@ -51,40 +66,46 @@ export {
   isVariable,
   isVersus,
 } from './parser/ast.js';
-
-// * RNG exports
-export type { RNG } from './rng/types.js';
+export { MAX_PARSE_DEPTH, ParseError, parse } from './parser/parser.js';
+export type { RngState } from './rng/seeded.js';
 export { SeededRNG } from './rng/seeded.js';
-
-// * Evaluator exports
-export {
-  DEFAULT_MAX_DICE,
-  DEFAULT_MAX_EXPLODE_ITERATIONS,
-  DEFAULT_MAX_REROLL_ITERATIONS,
-  evaluate,
-  EvaluatorError,
-} from './evaluator/evaluator.js';
+export type { RNG } from './rng/types.js';
+export type { RollOptions } from './roll.js';
+export { roll } from './roll.js';
 export type {
   CompareOp,
   ComparePoint,
   DieModifier,
   DieResult,
   EvaluateOptions,
-  ModifierSpec,
+  EvaluationOptions,
+  KeepDropSpec,
   ResolvedComparePoint,
   ResolvedCritThreshold,
   RollPart,
+  RollPartBase,
   RollPartType,
   RollResult,
 } from './types.js';
 export { DegreeOfSuccess } from './types.js';
 
-// * Public API
-export { roll } from './roll.js';
-export type { RollOptions } from './roll.js';
-
-// ? Named import — Bun's bundler tree-shakes the JSON module down to the
-//   single used property, so the full manifest is not embedded in dist.
-import { version } from '../package.json';
-
+/**
+ * Installed roll-parser version — the exact string in `package.json`, so
+ * pre-releases keep their suffix (`'3.0.0-beta.0'`). Sourced from the
+ * generated `src/version.ts`, kept in sync with the manifest by
+ * `bun run generate:version` and gated by `check:version` and CI.
+ *
+ * Useful in bug reports and for feature-gating against a minimum version. The
+ * CLI prints it for `--version` and in the `--help` header.
+ *
+ * @example
+ * ```typescript
+ * import { VERSION } from 'roll-parser';
+ *
+ * VERSION; // e.g. '3.0.0', or '3.1.0-beta.0' on a pre-release
+ * VERSION.startsWith('3.'); // true
+ * ```
+ *
+ * @category Core
+ */
 export const VERSION: string = version;

package/src/lexer/lexer.ts

@@ -5,24 +5,72 @@
  */
 
 import type { RollParserErrorCode } from '../errors.js';
-import { RollParserError } from '../errors.js';
+import { describeValue, RollParserError } from '../errors.js';
 import { type Token, TokenType } from './tokens.js';
 
 /**
  * Error thrown when the lexer encounters an invalid character.
+ *
+ * `position` is a zero-based UTF-16 offset into the input. It is deliberately
+ * absent from `message` — read it from the field, or uniformly across all
+ * roll-parser errors via `getErrorSpan`.
+ *
+ * Codes: `UNEXPECTED_CHARACTER` for a character that cannot start any token,
+ * `UNEXPECTED_IDENTIFIER` for a word that is not a known keyword.
+ *
+ * @example
+ * ```typescript
+ * import { LexerError, roll } from 'roll-parser';
+ *
+ * try {
+ *   roll('2d6+&');
+ * } catch (error) {
+ *   const typed = error as LexerError;
+ *   typed.code; // 'UNEXPECTED_CHARACTER'
+ *   typed.character; // '&'
+ *   typed.position; // 4
+ * }
+ * ```
+ *
+ * @category Errors
  */
 export class LexerError extends RollParserError {
+  /** Zero-based UTF-16 offset of the offending character in the input. */
   readonly position: number;
+  /**
+   * The offending text — a single character for `UNEXPECTED_CHARACTER` (the
+   * whole code point, so astral symbols are not split into surrogates), or
+   * the unrecognized word for `UNEXPECTED_IDENTIFIER`.
+   */
   readonly character: string;
 
-  constructor(message: string, code: RollParserErrorCode, position: number, character: string) {
-    super(`${message} at position ${position}: '${character}'`, code);
+  constructor(
+    message: string,
+    code: RollParserErrorCode,
+    position: number,
+    character: string,
+    options?: ErrorOptions,
+  ) {
+    super(`${message}: '${character}'`, code, options);
     this.name = 'LexerError';
     this.position = position;
     this.character = character;
   }
 }
 
+//
+// * Character codes
+//
+
+// Range tests compare code units: `char.toLowerCase()` per character allocated
+// a string on the lexer's hottest loop.
+const CHAR_DIGIT_0 = 48;
+const CHAR_DIGIT_9 = 57;
+const CHAR_UPPER_A = 65;
+const CHAR_UPPER_Z = 90;
+const CHAR_LOWER_A = 97;
+const CHAR_LOWER_Z = 122;
+
 /** Known identifier keywords mapped to their token types. */
 const IDENTIFIER_KEYWORDS: Record<string, TokenType> = {
   kh: TokenType.KEEP_HIGH,
@@ -39,6 +87,8 @@ const IDENTIFIER_KEYWORDS: Record<string, TokenType> = {
   ceil: TokenType.FUNCTION,
   round: TokenType.FUNCTION,
   abs: TokenType.FUNCTION,
+  sqrt: TokenType.FUNCTION,
+  pow: TokenType.FUNCTION,
   max: TokenType.FUNCTION,
   min: TokenType.FUNCTION,
   s: TokenType.SORT_ASC,
@@ -106,22 +156,18 @@ export class Lexer {
     const startPos = this.pos;
     const char = this.peek();
 
-    // * Numbers
     if (this.isDigit(char)) {
       return this.scanNumber();
     }
 
-    // * Identifiers (d, kh, kl, dh, dl, r, ro, f, vs, floor, ceil, ...)
     if (this.isAlpha(char)) {
       return this.scanIdentifier();
     }
 
-    // * Variable reference
     if (char === '@') {
       return this.scanAt();
     }
 
-    // * Operators and punctuation
     this.advance();
 
     switch (char) {
@@ -166,8 +212,7 @@ export class Lexer {
         if (this.match('!')) {
           return this.createTokenAt(TokenType.EXPLODE_COMPOUND, '!!', startPos);
         }
-        if (!this.isAtEnd() && this.peek().toLowerCase() === 'p') {
-          this.advance();
+        if (this.match('p') || this.match('P')) {
           return this.createTokenAt(TokenType.EXPLODE_PENETRATING, '!p', startPos);
         }
         return this.createTokenAt(TokenType.EXPLODE, char, startPos);
@@ -181,7 +226,9 @@ export class Lexer {
     }
   }
 
+  //
   // * Private helpers
+  //
 
   private skipWhitespace(): void {
     while (!this.isAtEnd() && this.isWhitespace(this.peek())) {
@@ -189,24 +236,23 @@ export class Lexer {
     }
   }
 
+  // Scanners slice once from a recorded start offset rather than accumulating
+  // `value += this.advance()` — one string per token instead of one per character.
   private scanNumber(): Token {
     const startPos = this.pos;
-    let value = '';
 
-    // Integer part
     while (!this.isAtEnd() && this.isDigit(this.peek())) {
-      value += this.advance();
+      this.pos++;
     }
 
-    // Decimal part
     if (!this.isAtEnd() && this.peek() === '.' && this.isDigit(this.peekNext())) {
-      value += this.advance(); // consume '.'
+      this.pos++;
       while (!this.isAtEnd() && this.isDigit(this.peek())) {
-        value += this.advance();
+        this.pos++;
       }
     }
 
-    return this.createTokenAt(TokenType.NUMBER, value, startPos);
+    return this.createTokenAt(TokenType.NUMBER, this.input.slice(startPos, this.pos), startPos);
   }
 
   /**
@@ -227,18 +273,15 @@ export class Lexer {
     const first = this.peek();
     const second = this.peekNext();
     if ((first === 'd' || first === 'D') && (second === 'f' || second === 'F')) {
-      this.advance();
-      this.advance();
+      this.pos += 2;
       return this.createTokenAt(TokenType.DICE_FATE, 'df', startPos);
     }
 
-    let value = '';
-
     while (!this.isAtEnd() && this.isAlpha(this.peek())) {
-      value += this.advance();
+      this.pos++;
     }
 
-    const lower = value.toLowerCase();
+    const lower = this.input.slice(startPos, this.pos).toLowerCase();
 
     if (lower === 'd' && !this.isAtEnd() && this.peek() === '%') {
       this.advance();
@@ -272,11 +315,11 @@ export class Lexer {
    */
   private scanAt(): Token {
     const startPos = this.pos;
-    this.advance(); // consume '@'
+    this.advance();
 
     let name: string;
     if (!this.isAtEnd() && this.peek() === '{') {
-      this.advance(); // consume '{'
+      this.advance();
       const nameStart = this.pos;
       while (!this.isAtEnd() && this.peek() !== '}' && this.peek() !== '\n') {
         this.advance();
@@ -285,7 +328,7 @@ export class Lexer {
         throw new LexerError('Unterminated @{...} variable', 'UNEXPECTED_CHARACTER', startPos, '@');
       }
       name = this.input.slice(nameStart, this.pos);
-      this.advance(); // consume '}'
+      this.advance();
     } else {
       const nameStart = this.pos;
       if (this.isAtEnd() || !this.isIdentifierStart(this.peek())) {
@@ -324,13 +367,19 @@ export class Lexer {
     return this.pos >= this.input.length;
   }
 
+  // `NaN` from an empty `peek()` fails every comparison, so end-of-input
+  // still reads as "not a digit / not alpha" without an extra guard.
   private isDigit(char: string): boolean {
-    return char >= '0' && char <= '9';
+    const code = char.charCodeAt(0);
+    return code >= CHAR_DIGIT_0 && code <= CHAR_DIGIT_9;
   }
 
   private isAlpha(char: string): boolean {
-    const c = char.toLowerCase();
-    return c >= 'a' && c <= 'z';
+    const code = char.charCodeAt(0);
+    return (
+      (code >= CHAR_LOWER_A && code <= CHAR_LOWER_Z) ||
+      (code >= CHAR_UPPER_A && code <= CHAR_UPPER_Z)
+    );
   }
 
   private isIdentifierStart(char: string): boolean {
@@ -345,8 +394,8 @@ export class Lexer {
     return char === ' ' || char === '\t' || char === '\n' || char === '\r';
   }
 
-  // ? Both factories run after the token's characters were consumed, so
-  //   `this.pos` is the exclusive end offset.
+  // Both factories run after the token's characters were consumed, so
+  // `this.pos` is the exclusive end offset.
   private createToken(type: TokenType, value: string): Token {
     return { type, value, position: this.pos, end: this.pos };
   }
@@ -357,18 +406,42 @@ export class Lexer {
 }
 
 /**
- * Tokenize a dice notation string.
+ * Tokenizes a dice notation string. The first stage of the pipeline —
+ * {@link parse} calls it for you; reach for `lex` directly only to build a
+ * syntax highlighter or an editor integration.
+ *
+ * Notation is case-insensitive and whitespace-tolerant: `2D20 + 5` and
+ * `2d20+5` produce the same tokens, and identifier tokens carry a lowercased
+ * `value`. The one exception is `@name`, whose case is preserved.
  *
  * @param input - The dice notation to tokenize
- * @returns Array of tokens including EOF
- * @throws {LexerError} If an invalid character is encountered
+ * @returns Every token in source order, always ending with one
+ *   `TokenType.EOF` token
+ * @throws {LexerError} If an invalid character or unknown identifier is found
+ * @throws {RollParserError} `INVALID_NOTATION_TYPE` when `input` is not a
+ *   string — raised before scanning, so it carries no position
  *
  * @example
  * ```typescript
+ * import { lex, TokenType } from 'roll-parser';
+ *
  * const tokens = lex('2d20+5');
- * // [NUMBER(2), DICE, NUMBER(20), PLUS, NUMBER(5), EOF]
+ * tokens.length; // 6 — NUMBER DICE NUMBER PLUS NUMBER EOF
+ * tokens[0]; // { type: TokenType.NUMBER, value: '2', position: 0, end: 1 }
+ * tokens[1].type === TokenType.DICE; // true
+ * tokens.at(-1)?.type === TokenType.EOF; // true
  * ```
+ *
+ * @category Core
  */
 export function lex(input: string): Token[] {
+  // ! The pipeline's only notation type guard — `parse` and `roll` both funnel through here.
+  if (typeof input !== 'string') {
+    throw new RollParserError(
+      `Notation must be a string, received ${describeValue(input)}`,
+      'INVALID_NOTATION_TYPE',
+    );
+  }
+
   return new Lexer(input).tokenize();
 }

package/src/lexer/tokens.ts

@@ -9,6 +9,8 @@
  *
  * Grouped semantically. Numeric values are stable identifiers — the specific
  * numbers don't matter, but they must be unique.
+ *
+ * @category AST
  */
 export enum TokenType {
   //
@@ -116,7 +118,11 @@ export enum TokenType {
   // * Functions
   //
 
-  /** Math function: 'floor', 'ceil', 'round', 'abs', 'max', 'min' */
+  /**
+   * Math function: 'floor', 'ceil', 'round', 'abs', 'sqrt', 'pow', 'max',
+   * 'min'. In postfix position, 'min'/'max' double as per-die clamp
+   * modifiers (`4d6min2`) — the parser decides by position, not the lexer.
+   */
   FUNCTION = 28,
 
   //
@@ -169,19 +175,38 @@ export enum TokenType {
 }
 
 /**
- * A token produced by the lexer.
+ * A token produced by {@link lex}: what it is, the text it came from, and
+ * where in the input that text sits.
+ *
+ * `position`/`end` are a half-open range, so `input.slice(position, end)`
+ * recovers the original source text — useful for syntax highlighting, where
+ * `value` alone is lossy.
+ *
+ * @example
+ * ```typescript
+ * import { lex, TokenType } from 'roll-parser';
+ *
+ * const input = '4D6KH3';
+ * const tokens = lex(input);
+ * tokens[1]; // { type: TokenType.DICE, value: 'd', position: 1, end: 2 }
+ * tokens[3].type === TokenType.KEEP_HIGH; // true
+ * input.slice(tokens[3].position, tokens[3].end); // 'KH' — original casing
+ * tokens[3].value; // 'kh' — normalized
+ * ```
+ *
+ * @category AST
  */
 export type Token = {
   /** The type of this token */
-  type: TokenType;
+  readonly type: TokenType;
   /** The raw string value from input (lowercased for identifiers) */
-  value: string;
+  readonly value: string;
   /** Zero-based start offset in the input string (UTF-16 code units) */
-  position: number;
+  readonly position: number;
   /**
    * Zero-based end offset (exclusive). Not always `position + value.length` —
    * braced variables (`@{name}` stores only `name`) and case-normalized
    * identifiers consume more input than their `value` retains.
    */
-  end: number;
+  readonly end: number;
 };