roll-parser 2.3.2 → 3.0.0-beta.0

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

@@ -0,0 +1,59 @@
+/**
+ * Success counting modifier.
+ *
+ * Transforms a dice pool into a signed success count: each die matching the
+ * success `threshold` contributes +1, each die matching the optional
+ * `failThreshold` contributes -1. When a single die matches both thresholds,
+ * success wins (checked first).
+ *
+ * Dropped dice (from a preceding keep/drop or intermediate reroll) are
+ * excluded from counting and are never tagged.
+ *
+ * Mutates the input pool in place to add `'success'` / `'failure'` modifier
+ * flags — mirrors the mutation pattern of explode and reroll modifiers.
+ *
+ * @module evaluator/modifiers/success-count
+ */
+
+import type { CompareOp, DieResult } from '../../types.js';
+import { matchesCondition } from './compare.js';
+
+export type ResolvedThreshold = {
+  operator: CompareOp;
+  value: number;
+};
+
+export type SuccessCountResult = {
+  total: number;
+  successes: number;
+  failures: number;
+};
+
+export function countSuccesses(
+  dice: DieResult[],
+  threshold: ResolvedThreshold,
+  failThreshold?: ResolvedThreshold,
+): SuccessCountResult {
+  let successes = 0;
+  let failures = 0;
+
+  for (const die of dice) {
+    if (die.modifiers.includes('dropped')) continue;
+
+    if (matchesCondition(die.result, threshold.operator, threshold.value)) {
+      die.modifiers.push('success');
+      successes += 1;
+      continue;
+    }
+
+    if (
+      failThreshold != null &&
+      matchesCondition(die.result, failThreshold.operator, failThreshold.value)
+    ) {
+      die.modifiers.push('failure');
+      failures += 1;
+    }
+  }
+
+  return { total: successes - failures, successes, failures };
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Roll Parser - Dice notation parser for tabletop RPGs.
+ *
+ * @module roll-parser
+ */
+
+// * Error hierarchy
+export { RollParserError, isRollParserError } from './errors.js';
+export type { RollParserErrorCode } from './errors.js';
+
+// * Lexer exports
+export { LexerError } from './lexer/lexer.js';
+
+// * Parser exports
+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.js';
+export {
+  isBinaryOp,
+  isCritThreshold,
+  isDice,
+  isExplode,
+  isFateDice,
+  isFunctionCall,
+  isGroup,
+  isGrouped,
+  isLiteral,
+  isModifier,
+  isReroll,
+  isSort,
+  isSuccessCount,
+  isUnaryOp,
+  isVariable,
+  isVersus,
+} from './parser/ast.js';
+
+// * RNG exports
+export type { RNG } from './rng/types.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 {
+  CompareOp,
+  ComparePoint,
+  DieModifier,
+  DieResult,
+  EvaluateOptions,
+  ModifierSpec,
+  ResolvedComparePoint,
+  ResolvedCritThreshold,
+  RollPart,
+  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';
+
+export const VERSION: string = version;

package/src/lexer/lexer.ts

@@ -0,0 +1,374 @@
+/**
+ * Dice notation lexer with character-by-character scanning.
+ *
+ * @module lexer/lexer
+ */
+
+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.
+ */
+export class LexerError extends RollParserError {
+  readonly position: number;
+  readonly character: string;
+
+  constructor(message: string, code: RollParserErrorCode, position: number, character: string) {
+    super(`${message} at position ${position}: '${character}'`, code);
+    this.name = 'LexerError';
+    this.position = position;
+    this.character = character;
+  }
+}
+
+/** Known identifier keywords mapped to their token types. */
+const IDENTIFIER_KEYWORDS: Record<string, TokenType> = {
+  kh: TokenType.KEEP_HIGH,
+  kl: TokenType.KEEP_LOW,
+  k: TokenType.KEEP_HIGH,
+  dh: TokenType.DROP_HIGH,
+  dl: TokenType.DROP_LOW,
+  d: TokenType.DICE,
+  r: TokenType.REROLL,
+  ro: TokenType.REROLL_ONCE,
+  f: TokenType.FAIL,
+  vs: TokenType.VS,
+  floor: TokenType.FUNCTION,
+  ceil: TokenType.FUNCTION,
+  round: TokenType.FUNCTION,
+  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.
+ *
+ * Produces a stream of tokens from an input string using character-by-character
+ * scanning with maximal munch for multi-character tokens.
+ */
+export class Lexer {
+  private pos = 0;
+  private readonly input: string;
+
+  constructor(input: string) {
+    this.input = input;
+  }
+
+  /**
+   * Tokenize the entire input and return all tokens.
+   */
+  tokenize(): Token[] {
+    const tokens: Token[] = [];
+
+    while (true) {
+      const token = this.nextToken();
+      tokens.push(token);
+      if (token.type === TokenType.EOF) break;
+    }
+
+    return tokens;
+  }
+
+  /**
+   * Get the next token from the input.
+   */
+  nextToken(): Token {
+    this.skipWhitespace();
+
+    if (this.isAtEnd()) {
+      return this.createToken(TokenType.EOF, '');
+    }
+
+    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) {
+      case '+':
+        return this.createTokenAt(TokenType.PLUS, char, startPos);
+      case '-':
+        return this.createTokenAt(TokenType.MINUS, char, startPos);
+      case '*':
+        if (this.match('*')) {
+          return this.createTokenAt(TokenType.POWER, '**', startPos);
+        }
+        return this.createTokenAt(TokenType.MULTIPLY, char, startPos);
+      case '/':
+        return this.createTokenAt(TokenType.DIVIDE, char, startPos);
+      case '%':
+        return this.createTokenAt(TokenType.MODULO, char, startPos);
+      case '^':
+        return this.createTokenAt(TokenType.POWER, char, startPos);
+      case '(':
+        return this.createTokenAt(TokenType.LPAREN, char, startPos);
+      case ')':
+        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);
+        }
+        return this.createTokenAt(TokenType.GREATER, char, startPos);
+      case '<':
+        if (this.match('=')) {
+          return this.createTokenAt(TokenType.LESS_EQUAL, '<=', startPos);
+        }
+        return this.createTokenAt(TokenType.LESS, char, startPos);
+      case '=':
+        return this.createTokenAt(TokenType.EQUAL, char, startPos);
+      case '!':
+        if (this.match('!')) {
+          return this.createTokenAt(TokenType.EXPLODE_COMPOUND, '!!', startPos);
+        }
+        if (!this.isAtEnd() && this.peek().toLowerCase() === 'p') {
+          this.advance();
+          return this.createTokenAt(TokenType.EXPLODE_PENETRATING, '!p', startPos);
+        }
+        return this.createTokenAt(TokenType.EXPLODE, char, startPos);
+      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);
+      }
+    }
+  }
+
+  // * Private helpers
+
+  private skipWhitespace(): void {
+    while (!this.isAtEnd() && this.isWhitespace(this.peek())) {
+      this.advance();
+    }
+  }
+
+  private scanNumber(): Token {
+    const startPos = this.pos;
+    let value = '';
+
+    // Integer part
+    while (!this.isAtEnd() && this.isDigit(this.peek())) {
+      value += this.advance();
+    }
+
+    // Decimal part
+    if (!this.isAtEnd() && this.peek() === '.' && this.isDigit(this.peekNext())) {
+      value += this.advance(); // consume '.'
+      while (!this.isAtEnd() && this.isDigit(this.peek())) {
+        value += this.advance();
+      }
+    }
+
+    return this.createTokenAt(TokenType.NUMBER, value, startPos);
+  }
+
+  /**
+   * Scans an identifier using full-accumulation: collects all consecutive
+   * alpha characters, then classifies the result against known keywords.
+   *
+   * Special cases run before/after the accumulation loop:
+   * - `dF` / `Df` / `dF` / `DF` produces DICE_FATE. Must be handled BEFORE
+   *   the loop because `F` is alpha and would otherwise be greedily merged
+   *   into identifiers like `dfkh` (from `4dFkh2`) or `dfdf` (from `dFdF`).
+   *   Reserves the `d[fF]` prefix namespace for Fate dice.
+   * - Bare `d` followed by `%` produces DICE_PERCENT. `%` is not alpha so the
+   *   accumulation loop stops naturally and the post-loop check handles it.
+   */
+  private scanIdentifier(): Token {
+    const startPos = this.pos;
+
+    const first = this.peek();
+    const second = this.peekNext();
+    if ((first === 'd' || first === 'D') && (second === 'f' || second === 'F')) {
+      this.advance();
+      this.advance();
+      return this.createTokenAt(TokenType.DICE_FATE, 'df', startPos);
+    }
+
+    let value = '';
+
+    while (!this.isAtEnd() && this.isAlpha(this.peek())) {
+      value += this.advance();
+    }
+
+    const lower = value.toLowerCase();
+
+    if (lower === 'd' && !this.isAtEnd() && this.peek() === '%') {
+      this.advance();
+      return this.createTokenAt(TokenType.DICE_PERCENT, 'd%', startPos);
+    }
+
+    const tokenType = IDENTIFIER_KEYWORDS[lower];
+    if (tokenType != null) {
+      return this.createTokenAt(tokenType, lower, startPos);
+    }
+
+    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 {
+    return this.input[this.pos] ?? '';
+  }
+
+  private peekNext(): string {
+    return this.input[this.pos + 1] ?? '';
+  }
+
+  private advance(): string {
+    return this.input[this.pos++] ?? '';
+  }
+
+  private match(expected: string): boolean {
+    if (this.isAtEnd()) return false;
+    if (this.input[this.pos] !== expected) return false;
+    this.pos++;
+    return true;
+  }
+
+  private isAtEnd(): boolean {
+    return this.pos >= this.input.length;
+  }
+
+  private isDigit(char: string): boolean {
+    return char >= '0' && char <= '9';
+  }
+
+  private isAlpha(char: string): boolean {
+    const c = char.toLowerCase();
+    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, end: this.pos };
+  }
+
+  private createTokenAt(type: TokenType, value: string, position: number): Token {
+    return { type, value, position, end: this.pos };
+  }
+}
+
+/**
+ * Tokenize a dice notation string.
+ *
+ * @param input - The dice notation to tokenize
+ * @returns Array of tokens including EOF
+ * @throws {LexerError} If an invalid character is encountered
+ *
+ * @example
+ * ```typescript
+ * const tokens = lex('2d20+5');
+ * // [NUMBER(2), DICE, NUMBER(20), PLUS, NUMBER(5), EOF]
+ * ```
+ */
+export function lex(input: string): Token[] {
+  return new Lexer(input).tokenize();
+}

package/src/lexer/tokens.ts

@@ -0,0 +1,187 @@
+/**
+ * Token type definitions for the dice notation lexer.
+ *
+ * @module lexer/tokens
+ */
+
+/**
+ * Token types for dice notation.
+ *
+ * Grouped semantically. Numeric values are stable identifiers — the specific
+ * numbers don't matter, but they must be unique.
+ */
+export enum TokenType {
+  //
+  // * Literals
+  //
+
+  /** Numeric literal: integer or decimal */
+  NUMBER = 0,
+
+  //
+  // * Dice operators
+  //
+
+  /** Dice operator: 'd' or 'D' */
+  DICE = 1,
+  /** Percentile dice operator: 'd%' (alias for d100) */
+  DICE_PERCENT = 2,
+  /** Fate/Fudge dice operator: 'dF' */
+  DICE_FATE = 3,
+
+  //
+  // * Arithmetic operators
+  //
+
+  /** Addition operator: '+' */
+  PLUS = 4,
+  /** Subtraction operator: '-' */
+  MINUS = 5,
+  /** Multiplication operator: '*' */
+  MULTIPLY = 6,
+  /** Division operator: '/' */
+  DIVIDE = 7,
+  /** Modulo operator: '%' */
+  MODULO = 8,
+  /** Power operator: '**' or '^' */
+  POWER = 9,
+
+  //
+  // * Comparison operators
+  //
+
+  /** Greater than: '>' */
+  GREATER = 10,
+  /** Greater than or equal: '>=' */
+  GREATER_EQUAL = 11,
+  /** Less than: '<' */
+  LESS = 12,
+  /** Less than or equal: '<=' */
+  LESS_EQUAL = 13,
+  /** Equal: '=' */
+  EQUAL = 14,
+
+  //
+  // * Grouping and punctuation
+  //
+
+  /** Left parenthesis: '(' */
+  LPAREN = 15,
+  /** Right parenthesis: ')' */
+  RPAREN = 16,
+  /** Argument separator: ',' */
+  COMMA = 17,
+
+  //
+  // * Keep/drop modifiers
+  //
+
+  /** Keep highest modifier: 'kh' or 'k' */
+  KEEP_HIGH = 18,
+  /** Keep lowest modifier: 'kl' */
+  KEEP_LOW = 19,
+  /** Drop highest modifier: 'dh' */
+  DROP_HIGH = 20,
+  /** Drop lowest modifier: 'dl' */
+  DROP_LOW = 21,
+
+  //
+  // * Explode modifiers
+  //
+
+  /** Standard explode: '!' */
+  EXPLODE = 22,
+  /** Compounding explode: '!!' */
+  EXPLODE_COMPOUND = 23,
+  /** Penetrating explode: '!p' */
+  EXPLODE_PENETRATING = 24,
+
+  //
+  // * Reroll modifiers
+  //
+
+  /** Recursive reroll: 'r' */
+  REROLL = 25,
+  /** Reroll once: 'ro' */
+  REROLL_ONCE = 26,
+
+  //
+  // * Success counting
+  //
+
+  /** Fail marker: 'f' */
+  FAIL = 27,
+
+  //
+  // * Functions
+  //
+
+  /** Math function: 'floor', 'ceil', 'round', 'abs', 'max', 'min' */
+  FUNCTION = 28,
+
+  //
+  // * Keywords
+  //
+
+  /** 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 = 37,
+}
+
+/**
+ * A token produced by the lexer.
+ */
+export type Token = {
+  /** The type of this token */
+  type: TokenType;
+  /** The raw string value from input (lowercased for identifiers) */
+  value: 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;
+};