roll-parser 3.0.0-alpha.0 → 3.0.0-beta.0

package/src/evaluator/index.ts

@@ -4,11 +4,11 @@
  * @module evaluator
  */
 
-export { DEFAULT_MAX_DICE, evaluate, EvaluatorError } from './evaluator';
+export { DEFAULT_MAX_DICE, evaluate, EvaluatorError } from './evaluator.js';
 export {
   applyDropHighest,
   applyDropLowest,
   applyKeepHighest,
   applyKeepLowest,
   sumKeptDice,
-} from './modifiers/keep-drop';
+} from './modifiers/keep-drop.js';

package/src/evaluator/modifiers/compare.ts

@@ -8,7 +8,7 @@
  * @module evaluator/modifiers/compare
  */
 
-import type { CompareOp } from '../../types';
+import type { CompareOp } from '../../types.js';
 
 /**
  * Compares a die result against a fixed comparison threshold.

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

@@ -0,0 +1,59 @@
+/**
+ * Critical / fumble threshold modifier.
+ *
+ * Overrides the default `critical`/`fumble` flag logic for a dice pool.
+ * `cs` and `cf` are independent (Roll20 semantics): the evaluator passes
+ * `['default']` for a side with no explicit thresholds, so overriding one
+ * side never wipes the other. An empty threshold array (not produced by the
+ * evaluator) would force the corresponding flag to `false` on every die.
+ * Meta dice (rolled to compute counts/sides/modifier args) are skipped so
+ * their bookkeeping stays untouched.
+ *
+ * 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
+ * whether they contributed to the total.
+ *
+ * @module evaluator/modifiers/crit-threshold
+ */
+
+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';
+
+/**
+ * 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.
+ */
+export function applyCritThresholds(
+  dice: DieResult[],
+  successThresholds: ResolvedCritThreshold[],
+  failThresholds: ResolvedCritThreshold[],
+): void {
+  for (const die of dice) {
+    if (die.modifiers.includes('meta')) continue;
+
+    die.critical = successThresholds.some((t) => matchesCrit(t, die));
+    die.fumble = failThresholds.some((t) => matchesFumble(t, die));
+  }
+}
+
+function matchesCrit(threshold: ResolvedCritThreshold, die: DieResult): boolean {
+  if (threshold === 'default') {
+    return die.result === die.sides && die.sides > 1;
+  }
+  return matchesCondition(die.result, threshold.operator, threshold.value);
+}
+
+function matchesFumble(threshold: ResolvedCritThreshold, die: DieResult): boolean {
+  if (threshold === 'default') {
+    // ? 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/explode.ts

@@ -8,10 +8,10 @@
  * @module evaluator/modifiers/explode
  */
 
-import type { RNG } from '../../rng/types';
-import type { CompareOp } from '../../types';
-import type { DieResult } from '../../types';
-import { EvaluatorError, type EvalEnv } from '../evaluator';
+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';
 
 /** Default maximum explosion iterations per die. */
 export const DEFAULT_MAX_EXPLODE_ITERATIONS = 1_000;
@@ -75,8 +75,11 @@ function explodeLimitError(maxIterations: number): EvaluatorError {
  * Returns true when the die is eligible to start exploding: it must not
  * already be dropped by a prior modifier, and its `sides` must be rollable.
  *
- * Fate dice (sides = 0) are skipped defensively — `rng.nextInt(1, 0)` is
- * invalid. Fate + explode is out of scope for the current feature set.
+ * The `sides < 1` branch is a defense-in-depth fallback — Fate dice
+ * (sides = 0) are rejected at parse time via `INVALID_EXPLODE_TARGET`
+ * (see `parseExplode` in `src/parser/parser.ts`), so this guard should
+ * 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 {
   if (die.modifiers.includes('dropped')) return false;
@@ -114,7 +117,7 @@ export function applyStandardExplode(
         result: next,
         modifiers: ['exploded', 'kept'],
         critical: next === sides && sides > 1,
-        fumble: next === 1,
+        fumble: next === 1 && sides > 1,
       });
       last = next;
       iterations += 1;
@@ -128,6 +131,10 @@ export function applyStandardExplode(
  * Compound explode: pool length stays the same. Each original die's `result`
  * accumulates every explosion roll, and gains the `'exploded'` modifier once
  * it actually exploded at least once.
+ *
+ * Mutates exploded dice in place — the same `DieResult` objects are shared
+ * between `RollResult.rolls` and the `RollPart` tree, and both must reflect
+ * post-explosion state.
  */
 export function applyCompoundExplode(
   pool: DieResult[],
@@ -135,8 +142,8 @@ export function applyCompoundExplode(
   rng: RNG,
   env: EvalEnv,
 ): DieResult[] {
-  return pool.map((original) => {
-    if (!canExplode(original)) return original;
+  for (const original of pool) {
+    if (!canExplode(original)) continue;
 
     const sides = original.sides;
     let accumulated = original.result;
@@ -155,21 +162,18 @@ export function applyCompoundExplode(
       iterations += 1;
     }
 
-    if (!exploded) return original;
-
-    return {
-      sides,
-      result: accumulated,
-      modifiers: original.modifiers.includes('exploded')
-        ? original.modifiers
-        : [...original.modifiers, 'exploded'],
-      // ? `critical` and `fumble` refer to the original triggering roll, but
-      //   after compounding the `result` is a sum. Mark critical if the
-      //   original roll was max; fumble stays as-is (can't accumulate down).
-      critical: original.critical,
-      fumble: original.fumble,
-    };
-  });
+    if (!exploded) continue;
+
+    // ? `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')) {
+      original.modifiers = [...original.modifiers, 'exploded'];
+    }
+  }
+
+  return pool;
 }
 
 /**
@@ -204,7 +208,7 @@ export function applyPenetratingExplode(
         result: stored,
         modifiers: ['exploded', 'kept'],
         critical: raw === sides && sides > 1,
-        fumble: raw === 1,
+        fumble: raw === 1 && sides > 1,
       });
       lastRaw = raw;
       iterations += 1;

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

@@ -4,7 +4,7 @@
  * @module evaluator/modifiers/keep-drop
  */
 
-import type { DieResult } from '../../types';
+import type { DieResult } from '../../types.js';
 
 /**
  * Marks all eligible dice as `'kept'`. Dice that already carry `'dropped'`

package/src/evaluator/modifiers/reroll.ts

@@ -9,10 +9,10 @@
  * @module evaluator/modifiers/reroll
  */
 
-import type { RNG } from '../../rng/types';
-import type { CompareOp, DieResult } from '../../types';
-import { EvaluatorError, type EvalEnv } from '../evaluator';
-import { matchesCondition } from './compare';
+import type { RNG } from '../../rng/types.js';
+import type { CompareOp, DieResult } from '../../types.js';
+import { EvaluatorError, type EvalEnv } from '../evaluator.js';
+import { matchesCondition } from './compare.js';
 
 /** Default maximum reroll iterations per die. */
 export const DEFAULT_MAX_REROLL_ITERATIONS = 1_000;
@@ -50,7 +50,7 @@ function rollReplacement(sides: number, rng: RNG, env: EvalEnv): DieResult {
     result,
     modifiers: [],
     critical: result === sides && sides > 1,
-    fumble: result === 1,
+    fumble: result === 1 && sides > 1,
   };
 }
 
@@ -105,24 +105,22 @@ 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.
     while (matchesCondition(current.result, operator, value)) {
       if (iterations >= env.maxRerollIterations) {
         throw rerollLimitError(env.maxRerollIterations);
       }
 
-      result.push({
-        ...current,
-        modifiers: [...stripSlotFlags(current.modifiers), 'rerolled', 'dropped'],
-      });
+      current.modifiers = [...stripSlotFlags(current.modifiers), 'rerolled', 'dropped'];
+      result.push(current);
 
       current = rollReplacement(current.sides, rng, env);
       iterations += 1;
     }
 
-    result.push({
-      ...current,
-      modifiers: [...stripSlotFlags(current.modifiers), 'kept'],
-    });
+    current.modifiers = [...stripSlotFlags(current.modifiers), 'kept'];
+    result.push(current);
   }
 
   return result;
@@ -148,24 +146,19 @@ export function applyRerollOnce(
       continue;
     }
 
+    // ? Mutate flags in place — see `applyRecursiveReroll`.
     if (!matchesCondition(original.result, operator, value)) {
-      result.push({
-        ...original,
-        modifiers: [...stripSlotFlags(original.modifiers), 'kept'],
-      });
+      original.modifiers = [...stripSlotFlags(original.modifiers), 'kept'];
+      result.push(original);
       continue;
     }
 
-    result.push({
-      ...original,
-      modifiers: [...stripSlotFlags(original.modifiers), 'rerolled', 'dropped'],
-    });
+    original.modifiers = [...stripSlotFlags(original.modifiers), 'rerolled', 'dropped'];
+    result.push(original);
 
     const replacement = rollReplacement(original.sides, rng, env);
-    result.push({
-      ...replacement,
-      modifiers: [...stripSlotFlags(replacement.modifiers), 'kept'],
-    });
+    replacement.modifiers = [...stripSlotFlags(replacement.modifiers), 'kept'];
+    result.push(replacement);
   }
 
   return result;

package/src/evaluator/modifiers/sort.ts

@@ -0,0 +1,30 @@
+/**
+ * Sort modifier implementation.
+ *
+ * Sort is purely cosmetic — it reorders the dice produced by its target in
+ * ascending or descending order of `result` without touching any flag
+ * (`kept`, `dropped`, `critical`, `fumble`, `rerolled`, `meta`) or the total.
+ * Dropped dice stay in the pool and sort alongside kept dice so readers can
+ * see where the dropped value landed in the ordered sequence.
+ *
+ * @module evaluator/modifiers/sort
+ */
+
+import type { DieResult } from '../../types.js';
+
+/**
+ * Returns a sorted copy of `dice` in the given order, preserving every die's
+ * original flags and metadata. Comparison is on `.result` — the raw face
+ * value is what the user sees in rendered output, so ordering by raw value
+ * matches the visual intent regardless of any `kept`/`dropped` flagging.
+ *
+ * Relies on `Array.prototype.sort` being stable — equal-valued dice retain
+ * their original insertion order.
+ */
+export function sortDice(dice: DieResult[], order: 'ascending' | 'descending'): DieResult[] {
+  const cmp =
+    order === 'ascending'
+      ? (a: DieResult, b: DieResult) => a.result - b.result
+      : (a: DieResult, b: DieResult) => b.result - a.result;
+  return [...dice].sort(cmp);
+}

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

@@ -15,8 +15,8 @@
  * @module evaluator/modifiers/success-count
  */
 
-import type { CompareOp, DieResult } from '../../types';
-import { matchesCondition } from './compare';
+import type { CompareOp, DieResult } from '../../types.js';
+import { matchesCondition } from './compare.js';
 
 export type ResolvedThreshold = {
   operator: CompareOp;

package/src/index.ts

@@ -5,45 +5,56 @@
  */
 
 // * Error hierarchy
-export { RollParserError, isRollParserError } from './errors';
-export type { RollParserErrorCode } from './errors';
+export { RollParserError, isRollParserError } from './errors.js';
+export type { RollParserErrorCode } from './errors.js';
 
 // * Lexer exports
-export { LexerError } from './lexer/lexer';
+export { LexerError } from './lexer/lexer.js';
 
 // * Parser exports
-export { parse, ParseError } from './parser/parser';
+export { parse, ParseError } from './parser/parser.js';
 export type {
   ASTNode,
   BinaryOpNode,
   DiceNode,
+  NodeSpan,
   ExplodeNode,
   FateDiceNode,
   FunctionCallNode,
+  GroupedNode,
   LiteralNode,
   ModifierNode,
   RerollNode,
   SuccessCountNode,
+  SortNode,
+  CritThresholdNode,
+  GroupNode,
   UnaryOpNode,
+  VariableNode,
   VersusNode,
-} from './parser/ast';
+} from './parser/ast.js';
 export {
   isBinaryOp,
+  isCritThreshold,
   isDice,
   isExplode,
   isFateDice,
   isFunctionCall,
+  isGroup,
+  isGrouped,
   isLiteral,
   isModifier,
   isReroll,
+  isSort,
   isSuccessCount,
   isUnaryOp,
+  isVariable,
   isVersus,
-} from './parser/ast';
+} from './parser/ast.js';
 
 // * RNG exports
-export type { RNG } from './rng/types';
-export { SeededRNG } from './rng/seeded';
+export type { RNG } from './rng/types.js';
+export { SeededRNG } from './rng/seeded.js';
 
 // * Evaluator exports
 export {
@@ -52,21 +63,28 @@ export {
   DEFAULT_MAX_REROLL_ITERATIONS,
   evaluate,
   EvaluatorError,
-} from './evaluator/evaluator';
+} from './evaluator/evaluator.js';
 export type {
   CompareOp,
   ComparePoint,
   DieModifier,
   DieResult,
   EvaluateOptions,
+  ModifierSpec,
+  ResolvedComparePoint,
+  ResolvedCritThreshold,
+  RollPart,
+  RollPartType,
   RollResult,
-} from './types';
-export { DegreeOfSuccess } from './types';
+} from './types.js';
+export { DegreeOfSuccess } from './types.js';
 
 // * Public API
-export { roll } from './roll';
-export type { RollOptions } from './roll';
+export { roll } from './roll.js';
+export type { RollOptions } from './roll.js';
 
-import pkg from '../package.json';
+// ? 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';
 
-export const VERSION: string = pkg.version;
+export const VERSION: string = version;

package/src/lexer/lexer.ts

@@ -4,9 +4,9 @@
  * @module lexer/lexer
  */
 
-import type { RollParserErrorCode } from '../errors';
-import { RollParserError } from '../errors';
-import { type Token, TokenType } from './tokens';
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import { type Token, TokenType } from './tokens.js';
 
 /**
  * Error thrown when the lexer encounters an invalid character.
@@ -41,8 +41,29 @@ const IDENTIFIER_KEYWORDS: Record<string, TokenType> = {
   abs: TokenType.FUNCTION,
   max: TokenType.FUNCTION,
   min: TokenType.FUNCTION,
+  s: TokenType.SORT_ASC,
+  sa: TokenType.SORT_ASC,
+  sd: TokenType.SORT_DESC,
+  cs: TokenType.CRIT_SUCCESS,
+  cf: TokenType.CRIT_FAIL,
 };
 
+/**
+ * Builds a hint for identifiers that start with a known keyword. Maximal
+ * munch merges adjacent modifiers when the first has no count — `4d6khs`
+ * lexes as one identifier `khs` instead of `kh` + `s`. Point the user at the
+ * explicit-count (or whitespace) split.
+ */
+function buildIdentifierHint(identifier: string): string {
+  for (let length = identifier.length - 1; length >= 1; length--) {
+    const prefix = identifier.slice(0, length);
+    if (IDENTIFIER_KEYWORDS[prefix] == null) continue;
+    const rest = identifier.slice(length);
+    return ` (did you mean '${prefix}' followed by '${rest}'? separate modifiers with a count or space, e.g. '${prefix}1${rest}')`;
+  }
+  return '';
+}
+
 /**
  * Lexer for dice notation.
  *
@@ -95,6 +116,11 @@ export class Lexer {
       return this.scanIdentifier();
     }
 
+    // * Variable reference
+    if (char === '@') {
+      return this.scanAt();
+    }
+
     // * Operators and punctuation
     this.advance();
 
@@ -120,6 +146,10 @@ export class Lexer {
         return this.createTokenAt(TokenType.RPAREN, char, startPos);
       case ',':
         return this.createTokenAt(TokenType.COMMA, char, startPos);
+      case '{':
+        return this.createTokenAt(TokenType.LBRACE, char, startPos);
+      case '}':
+        return this.createTokenAt(TokenType.RBRACE, char, startPos);
       case '>':
         if (this.match('=')) {
           return this.createTokenAt(TokenType.GREATER_EQUAL, '>=', startPos);
@@ -141,8 +171,13 @@ export class Lexer {
           return this.createTokenAt(TokenType.EXPLODE_PENETRATING, '!p', startPos);
         }
         return this.createTokenAt(TokenType.EXPLODE, char, startPos);
-      default:
-        throw new LexerError('Unexpected character', 'UNEXPECTED_CHARACTER', startPos, char);
+      default: {
+        // Surrogate pairs (emoji, astral symbols) span two code units —
+        // report the full code point instead of a lone surrogate ('�').
+        const codePoint = this.input.codePointAt(startPos);
+        const display = codePoint == null ? char : String.fromCodePoint(codePoint);
+        throw new LexerError('Unexpected character', 'UNEXPECTED_CHARACTER', startPos, display);
+      }
     }
   }
 
@@ -215,7 +250,55 @@ export class Lexer {
       return this.createTokenAt(tokenType, lower, startPos);
     }
 
-    throw new LexerError('Unexpected identifier', 'UNEXPECTED_IDENTIFIER', startPos, lower);
+    throw new LexerError(
+      `Unexpected identifier${buildIdentifierHint(lower)}`,
+      'UNEXPECTED_IDENTIFIER',
+      startPos,
+      lower,
+    );
+  }
+
+  /**
+   * Scans a variable reference introduced by `@`.
+   *
+   * Two forms:
+   * - Bare: `@name` where `name` matches `[A-Za-z_][A-Za-z0-9_]*` (case preserved).
+   * - Braced: `@{name}` where `name` is any run of printable characters except
+   *   `}` and newline (permits spaces, hyphens, digits).
+   *
+   * Case is preserved — distinct from `scanIdentifier`, which lowercases the
+   * captured value. The emitted token's `value` is the variable name without
+   * the leading `@` or the surrounding braces.
+   */
+  private scanAt(): Token {
+    const startPos = this.pos;
+    this.advance(); // consume '@'
+
+    let name: string;
+    if (!this.isAtEnd() && this.peek() === '{') {
+      this.advance(); // consume '{'
+      const nameStart = this.pos;
+      while (!this.isAtEnd() && this.peek() !== '}' && this.peek() !== '\n') {
+        this.advance();
+      }
+      if (this.isAtEnd() || this.peek() !== '}') {
+        throw new LexerError('Unterminated @{...} variable', 'UNEXPECTED_CHARACTER', startPos, '@');
+      }
+      name = this.input.slice(nameStart, this.pos);
+      this.advance(); // consume '}'
+    } else {
+      const nameStart = this.pos;
+      if (this.isAtEnd() || !this.isIdentifierStart(this.peek())) {
+        throw new LexerError('Empty @ variable name', 'UNEXPECTED_CHARACTER', startPos, '@');
+      }
+      this.advance();
+      while (!this.isAtEnd() && this.isIdentifierPart(this.peek())) {
+        this.advance();
+      }
+      name = this.input.slice(nameStart, this.pos);
+    }
+
+    return this.createTokenAt(TokenType.AT, name, startPos);
   }
 
   private peek(): string {
@@ -250,16 +333,26 @@ export class Lexer {
     return c >= 'a' && c <= 'z';
   }
 
+  private isIdentifierStart(char: string): boolean {
+    return this.isAlpha(char) || char === '_';
+  }
+
+  private isIdentifierPart(char: string): boolean {
+    return this.isAlpha(char) || this.isDigit(char) || char === '_';
+  }
+
   private isWhitespace(char: string): boolean {
     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.
   private createToken(type: TokenType, value: string): Token {
-    return { type, value, position: this.pos };
+    return { type, value, position: this.pos, end: this.pos };
   }
 
   private createTokenAt(type: TokenType, value: string, position: number): Token {
-    return { type, value, position };
+    return { type, value, position, end: this.pos };
   }
 }
 

package/src/lexer/tokens.ts

@@ -126,12 +126,46 @@ export enum TokenType {
   /** Versus operator: 'vs' */
   VS = 29,
 
+  //
+  // * Group boundaries
+  //
+
+  /** Left brace: '{' */
+  LBRACE = 30,
+  /** Right brace: '}' */
+  RBRACE = 31,
+
+  //
+  // * Variables
+  //
+
+  /** Variable reference prefix: '@' */
+  AT = 32,
+
+  //
+  // * Sort modifiers
+  //
+
+  /** Ascending sort: 's' or 'sa' */
+  SORT_ASC = 33,
+  /** Descending sort: 'sd' */
+  SORT_DESC = 34,
+
+  //
+  // * Crit thresholds
+  //
+
+  /** Critical success threshold: 'cs' */
+  CRIT_SUCCESS = 35,
+  /** Critical failure threshold: 'cf' */
+  CRIT_FAIL = 36,
+
   //
   // * End of input
   //
 
   /** End of input marker */
-  EOF = 30,
+  EOF = 37,
 }
 
 /**
@@ -142,6 +176,12 @@ export type Token = {
   type: TokenType;
   /** The raw string value from input (lowercased for identifiers) */
   value: string;
-  /** Zero-based position in the input string */
+  /** Zero-based start offset in the input string (UTF-16 code units) */
   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;
 };