roll-parser 2.3.2 → 3.0.0-beta.0

package/src/parser/parser.ts

@@ -0,0 +1,1239 @@
+/**
+ * Pratt parser for dice notation.
+ *
+ * @module parser/parser
+ */
+
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import { lex } from '../lexer/lexer.js';
+import { type Token, TokenType } from '../lexer/tokens.js';
+import type { CompareOp, ComparePoint } from '../types.js';
+import type {
+  ASTNode,
+  BinaryOpNode,
+  CritThreshold,
+  CritThresholdNode,
+  DiceNode,
+  ExplodeNode,
+  FateDiceNode,
+  FunctionCallNode,
+  GroupedNode,
+  GroupNode,
+  LiteralNode,
+  ModifierNode,
+  RerollNode,
+  SortNode,
+  SuccessCountNode,
+  UnaryOpNode,
+  VariableNode,
+  VersusNode,
+} from './ast.js';
+import {
+  containsDicePool,
+  containsFatePool,
+  containsMultiSubGroup,
+  containsVersus,
+  deepContainsDicePool,
+  isCritThreshold,
+  isSuccessCount,
+  unwrapTransparent,
+} from './ast.js';
+
+/**
+ * Error thrown when the parser encounters invalid syntax.
+ */
+export class ParseError extends RollParserError {
+  readonly position: number;
+  readonly token: Token | undefined;
+
+  constructor(message: string, code: RollParserErrorCode, position: number, token?: Token) {
+    super(`${message} at position ${position}`, code);
+    this.name = 'ParseError';
+    this.position = position;
+    this.token = token ?? undefined;
+  }
+}
+
+/**
+ * Binding power constants for operators.
+ * Higher values bind tighter. Right < Left for right-associativity.
+ *
+ * Precedence order (lowest to highest):
+ * - Versus (`vs`): 2-3 (lowest — full expressions on both sides)
+ * - Addition/subtraction: 10
+ * - Multiplication/division/modulo: 20
+ * - Unary minus: 25 (binds to complete dice expr: -1d4 = -(1d4))
+ * - Power: 30-31
+ * - Modifiers (postfix): 35 (must be < DICE_RIGHT to bind to complete dice expr)
+ * - Dice: 40-41
+ */
+const BP = {
+  // Versus (left-associative, lowest precedence — `1d20+10 vs 25+10` = `(1d20+10) vs (25+10)`)
+  VS_LEFT: 2,
+  VS_RIGHT: 3,
+  // Comparison operators used as the success-count LED. Must be below
+  // ADD/MUL so `XdY+N>T` parses as `(XdY+N)>T` and fails the pool-target
+  // guard with a clear error, instead of the `>` stealing `N` from the `+`.
+  COMPARE: 8,
+  // Addition/subtraction (left-associative)
+  ADD_LEFT: 10,
+  ADD_RIGHT: 11,
+  // Multiplication/division/modulo (left-associative)
+  MUL_LEFT: 20,
+  MUL_RIGHT: 21,
+  // Unary minus: between mul and power so -1d4 = -(1d4) not (-1)d4
+  UNARY: 25,
+  // Power (right-associative: left > right)
+  POW_LEFT: 31,
+  POW_RIGHT: 30,
+  // Postfix modifiers: must be < DICE_RIGHT so they bind to complete dice expr
+  MODIFIER: 35,
+  // Dice operator (highest math precedence)
+  DICE_LEFT: 40,
+  DICE_RIGHT: 41,
+} as const;
+
+/**
+ * Maximum expression nesting depth. Far beyond any human-authored notation —
+ * exists so adversarial input like 20,000 nested parens throws a typed
+ * `ParseError` instead of an uncaught `RangeError` stack overflow (which
+ * would also break the `isRollParserError` contract). Bounding parse depth
+ * also bounds AST depth, protecting the recursive AST walkers and evaluator.
+ */
+const MAX_PARSE_DEPTH = 128;
+
+/** Human-readable symbols for tokens named in `expect()` error messages. */
+const TOKEN_DISPLAY: Partial<Record<TokenType, string>> = {
+  [TokenType.LPAREN]: `'('`,
+  [TokenType.RPAREN]: `')'`,
+  [TokenType.LBRACE]: `'{'`,
+  [TokenType.RBRACE]: `'}'`,
+  [TokenType.COMMA]: `','`,
+};
+
+/**
+ * Arity table for math functions. `min` and `max` are inclusive.
+ * `POSITIVE_INFINITY` means unbounded (variadic).
+ */
+const FUNCTION_ARITY: Record<string, { min: number; max: number }> = {
+  floor: { min: 1, max: 1 },
+  ceil: { min: 1, max: 1 },
+  round: { min: 1, max: 1 },
+  abs: { min: 1, max: 1 },
+  max: { min: 2, max: Number.POSITIVE_INFINITY },
+  min: { min: 2, max: Number.POSITIVE_INFINITY },
+};
+
+/**
+ * Pratt parser for dice notation.
+ *
+ * Uses binding power (precedence) to handle operator associativity and
+ * precedence without left recursion issues.
+ */
+export class Parser {
+  private readonly tokens: Token[];
+  private pos = 0;
+  private depth = 0;
+
+  constructor(tokens: Token[]) {
+    this.tokens = tokens;
+  }
+
+  /**
+   * Parse the token stream into an AST.
+   */
+  parse(): ASTNode {
+    if (this.peek().type === TokenType.EOF) {
+      throw new ParseError('Unexpected end of input', 'UNEXPECTED_END', this.peek().position);
+    }
+
+    const ast = this.parseExpression(0);
+
+    // Ensure we consumed all tokens
+    if (this.peek().type !== TokenType.EOF) {
+      const token = this.peek();
+      throw new ParseError(
+        `Unexpected token '${token.value}'`,
+        'UNEXPECTED_TOKEN',
+        token.position,
+        token,
+      );
+    }
+
+    return ast;
+  }
+
+  /**
+   * Parse an expression with minimum binding power.
+   */
+  private parseExpression(minBp: number): ASTNode {
+    this.depth += 1;
+    if (this.depth > MAX_PARSE_DEPTH) {
+      throw new ParseError(
+        `Expression nesting exceeds the maximum depth of ${MAX_PARSE_DEPTH}`,
+        'MAX_DEPTH_EXCEEDED',
+        this.peek().position,
+        this.peek(),
+      );
+    }
+
+    try {
+      let left = this.parseNud();
+
+      while (this.hasTokens()) {
+        const token = this.peek();
+        const leftBp = this.getLeftBp(token);
+
+        if (leftBp < minBp) break;
+
+        this.advance();
+        left = this.parseLed(left, token);
+      }
+
+      return left;
+    } finally {
+      this.depth -= 1;
+    }
+  }
+
+  /**
+   * NUD - Null Denotation.
+   * Handles tokens that appear at the start of an expression (prefix position).
+   */
+  private parseNud(): ASTNode {
+    const token = this.advance();
+
+    switch (token.type) {
+      case TokenType.NUMBER:
+        return this.parseLiteral(token);
+
+      case TokenType.MINUS:
+        return this.parseUnaryMinus(token);
+
+      case TokenType.DICE:
+        return this.parsePrefixDice(token);
+
+      case TokenType.DICE_PERCENT:
+        return this.parsePrefixDicePercent(token);
+
+      case TokenType.DICE_FATE:
+        return this.parsePrefixFateDice(token);
+
+      case TokenType.LPAREN:
+        return this.parseGrouped(token);
+
+      case TokenType.LBRACE:
+        return this.parseGroup(token);
+
+      case TokenType.FUNCTION:
+        return this.parseFunctionCall(token);
+
+      case TokenType.AT:
+        return this.parseVariable(token);
+
+      case TokenType.EOF:
+        throw new ParseError('Unexpected end of input', 'UNEXPECTED_END', token.position);
+
+      default:
+        throw new ParseError(
+          `Unexpected token '${token.value}'`,
+          'UNEXPECTED_TOKEN',
+          token.position,
+          token,
+        );
+    }
+  }
+
+  /**
+   * LED - Left Denotation.
+   * Handles tokens that appear between expressions (infix/postfix position).
+   */
+  private parseLed(left: ASTNode, token: Token): ASTNode {
+    switch (token.type) {
+      case TokenType.DICE:
+        return this.parseInfixDice(left, token);
+
+      case TokenType.DICE_PERCENT:
+        return this.parseInfixDicePercent(left, token);
+
+      case TokenType.DICE_FATE:
+        return this.parseInfixFateDice(left, token);
+
+      case TokenType.PLUS:
+      case TokenType.MINUS:
+      case TokenType.MULTIPLY:
+      case TokenType.DIVIDE:
+      case TokenType.MODULO:
+      case TokenType.POWER:
+        return this.parseBinaryOp(left, token);
+
+      case TokenType.KEEP_HIGH:
+      case TokenType.KEEP_LOW:
+      case TokenType.DROP_HIGH:
+      case TokenType.DROP_LOW:
+        return this.parseModifier(left, token);
+
+      case TokenType.EXPLODE:
+      case TokenType.EXPLODE_COMPOUND:
+      case TokenType.EXPLODE_PENETRATING:
+        return this.parseExplode(left, token);
+
+      case TokenType.REROLL:
+      case TokenType.REROLL_ONCE:
+        return this.parseReroll(left, token);
+
+      case TokenType.SORT_ASC:
+      case TokenType.SORT_DESC:
+        return this.parseSort(left, token);
+
+      case TokenType.CRIT_SUCCESS:
+      case TokenType.CRIT_FAIL:
+        return this.parseCritThreshold(left, token);
+
+      case TokenType.GREATER:
+      case TokenType.GREATER_EQUAL:
+      case TokenType.LESS:
+      case TokenType.LESS_EQUAL:
+      case TokenType.EQUAL:
+        return this.parseSuccessCount(left, token);
+
+      case TokenType.VS:
+        return this.parseVersus(left, token);
+
+      default:
+        throw new ParseError(
+          `Unexpected infix token '${token.value}'`,
+          'UNEXPECTED_TOKEN',
+          token.position,
+          token,
+        );
+    }
+  }
+
+  // * Node parsers
+
+  /**
+   * 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(value: number, token: Token): LiteralNode {
+    return { type: 'Literal', value, start: token.position, end: token.position };
+  }
+
+  private parseLiteral(token: Token): LiteralNode {
+    return {
+      type: 'Literal',
+      value: Number.parseFloat(token.value),
+      start: token.position,
+      end: token.end,
+    };
+  }
+
+  private parseUnaryMinus(token: Token): UnaryOpNode {
+    const operand = this.parseExpression(BP.UNARY);
+    this.rejectSuccessCountTarget(operand, token);
+    return {
+      type: 'UnaryOp',
+      operator: '-',
+      operand,
+      start: token.position,
+      end: operand.end ?? token.end,
+    };
+  }
+
+  private parsePrefixDice(token: Token): DiceNode {
+    // d20 → Dice(1, 20)
+    const sides = this.parseExpression(BP.DICE_RIGHT);
+    this.rejectSuccessCountTarget(sides, token);
+    this.rejectVersusTarget(sides, token);
+    return {
+      type: 'Dice',
+      count: Parser.syntheticLiteral(1, token),
+      sides,
+      start: token.position,
+      end: sides.end ?? token.end,
+    };
+  }
+
+  private parseInfixDice(left: ASTNode, token: Token): DiceNode {
+    // 4d6 → Dice(4, 6)
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
+    const sides = this.parseExpression(BP.DICE_RIGHT);
+    this.rejectSuccessCountTarget(sides, token);
+    this.rejectVersusTarget(sides, token);
+    return {
+      type: 'Dice',
+      count: left,
+      sides,
+      start: left.start ?? token.position,
+      end: sides.end ?? token.end,
+    };
+  }
+
+  private parsePrefixDicePercent(token: Token): DiceNode {
+    // d% → Dice(1, 100)
+    return {
+      type: 'Dice',
+      count: Parser.syntheticLiteral(1, token),
+      sides: Parser.syntheticLiteral(100, token),
+      start: token.position,
+      end: token.end,
+    };
+  }
+
+  private parseInfixDicePercent(left: ASTNode, token: Token): DiceNode {
+    // 2d% → Dice(2, 100)
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
+    return {
+      type: 'Dice',
+      count: left,
+      sides: Parser.syntheticLiteral(100, token),
+      start: left.start ?? token.position,
+      end: token.end,
+    };
+  }
+
+  private parsePrefixFateDice(token: Token): FateDiceNode {
+    // dF → FateDice(1)
+    return {
+      type: 'FateDice',
+      count: Parser.syntheticLiteral(1, token),
+      start: token.position,
+      end: token.end,
+    };
+  }
+
+  private parseInfixFateDice(left: ASTNode, token: Token): FateDiceNode {
+    // 4dF → FateDice(4). Unlike parseInfixDice, there is no sides sub-parse,
+    // so modifiers (`kh`, `dl`, …) naturally bind at the outer Pratt loop
+    // without BP competition against a right-operand.
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
+    return {
+      type: 'FateDice',
+      count: left,
+      start: left.start ?? token.position,
+      end: token.end,
+    };
+  }
+
+  private parseGrouped(token: Token): GroupedNode {
+    const expression = this.parseExpression(0);
+    const close = this.expect(TokenType.RPAREN);
+    return { type: 'Grouped', expression, start: token.position, end: close.end };
+  }
+
+  private parseGroup(startToken: Token): GroupNode {
+    // ? `LBRACE`/`RBRACE`/`COMMA` all have `getLeftBp === -1`, so inner
+    //   `parseExpression(0)` calls terminate at the first `,` or `}` without
+    //   competing with modifier/arithmetic BPs.
+    if (this.peek().type === TokenType.RBRACE) {
+      throw new ParseError('Empty group', 'UNEXPECTED_TOKEN', startToken.position, startToken);
+    }
+
+    const expressions: ASTNode[] = [this.parseExpression(0)];
+    while (this.peek().type === TokenType.COMMA) {
+      this.advance();
+      expressions.push(this.parseExpression(0));
+    }
+
+    if (this.peek().type !== TokenType.RBRACE) {
+      const unterminated = this.peek();
+      throw new ParseError(
+        `Unterminated group: expected '}' or ','`,
+        'EXPECTED_TOKEN',
+        unterminated.position,
+        unterminated,
+      );
+    }
+    const close = this.advance();
+
+    return { type: 'Group', expressions, start: startToken.position, end: close.end };
+  }
+
+  private parseVariable(token: Token): VariableNode {
+    return { type: 'Variable', name: token.value, start: token.position, end: token.end };
+  }
+
+  private parseFunctionCall(token: Token): FunctionCallNode {
+    // `FUNCTION` has BP = -1 so callers stop here; `COMMA` and `RPAREN` also
+    // terminate inner `parseExpression(0)` calls, so argument boundaries are
+    // natural.
+    this.expect(TokenType.LPAREN);
+
+    const args: ASTNode[] = [];
+    if (this.peek().type !== TokenType.RPAREN) {
+      const first = this.parseExpression(0);
+      this.rejectSuccessCountTarget(first, token);
+      args.push(first);
+      while (this.peek().type === TokenType.COMMA) {
+        this.advance();
+        const next = this.parseExpression(0);
+        this.rejectSuccessCountTarget(next, token);
+        args.push(next);
+      }
+    }
+
+    const close = this.expect(TokenType.RPAREN);
+
+    const arity = FUNCTION_ARITY[token.value];
+    if (arity === undefined) {
+      // ? Unreachable in practice: lexer only emits FUNCTION for registered
+      // names. Kept defensive to keep parser/evaluator error-code contract
+      // symmetrical.
+      throw new ParseError(
+        `Unknown function '${token.value}'`,
+        'UNKNOWN_FUNCTION',
+        token.position,
+        token,
+      );
+    }
+
+    if (args.length < arity.min || args.length > arity.max) {
+      const expected =
+        arity.max === Number.POSITIVE_INFINITY
+          ? `at least ${arity.min}`
+          : arity.min === arity.max
+            ? `${arity.min}`
+            : `${arity.min}–${arity.max}`;
+      throw new ParseError(
+        `Function '${token.value}' expects ${expected} argument${arity.min === 1 && arity.max === 1 ? '' : 's'}, got ${args.length}`,
+        'INVALID_FUNCTION_ARITY',
+        token.position,
+        token,
+      );
+    }
+
+    return {
+      type: 'FunctionCall',
+      name: token.value,
+      args,
+      start: token.position,
+      end: close.end,
+    };
+  }
+
+  private parseBinaryOp(left: ASTNode, token: Token): BinaryOpNode {
+    this.rejectSuccessCountTarget(left, token);
+
+    const operator = this.getOperatorSymbol(token);
+    const rightBp = this.getRightBp(token);
+    const right = this.parseExpression(rightBp);
+
+    this.rejectSuccessCountTarget(right, token);
+
+    return {
+      type: 'BinaryOp',
+      operator,
+      left,
+      right,
+      start: left.start ?? token.position,
+      end: right.end ?? token.end,
+    };
+  }
+
+  /**
+   * 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(left: ASTNode, token: Token): void {
+    switch (left.type) {
+      case 'Dice':
+      case 'FateDice':
+      case 'Explode':
+      case 'Reroll':
+      case 'Modifier':
+      case 'Sort':
+      case 'CritThreshold':
+        throw new ParseError(
+          `Ambiguous dice chain: use 'dl'/'dh' to drop dice (4d6dl1) or parentheses for nested dice ((4d6)d1)`,
+          'AMBIGUOUS_DICE_CHAIN',
+          token.position,
+          token,
+        );
+      default:
+        return;
+    }
+  }
+
+  private rejectSuccessCountTarget(target: ASTNode, token: Token): void {
+    // ? Narrow unwrap: only `Grouped`. A `SuccessCount` cannot live inside
+    //   `Modifier`/`Sort`/`CritThreshold` because each of those parsers calls
+    //   this same reject on their target before constructing the wrapper —
+    //   so widening the set here would never match.
+    const node = unwrapTransparent(target, ['Grouped']);
+    if (isSuccessCount(node)) {
+      throw new ParseError(
+        `Cannot apply modifier after success counting`,
+        'INVALID_SUCCESS_COUNT_TARGET',
+        token.position,
+        token,
+      );
+    }
+  }
+
+  /**
+   * 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(
+    target: ASTNode,
+    token: Token,
+    action: string,
+    code: RollParserErrorCode,
+    singleSubRollPasses = false,
+  ): void {
+    const node = unwrapTransparent(target, ['Grouped', 'Modifier', 'Sort', 'CritThreshold']);
+    if (node.type !== 'Group') return;
+    if (singleSubRollPasses && node.expressions.length === 1) {
+      // ! Deep-walk the inner sub-expression — `unwrapTransparent` only peels
+      //   `Grouped`/`Modifier`/`Sort`/`CritThreshold`, so a multi-sub Group
+      //   buried under arithmetic (`{{1d6,2d8}+0}cs>5`), function calls
+      //   (`{abs({1d6,2d8})}cs>5`), or unary ops would otherwise revive the
+      //   exact dropped-die-flag bug from #97.
+      const inner = node.expressions[0];
+      if (inner != null && containsMultiSubGroup(inner)) {
+        throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
+      }
+      return;
+    }
+    throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
+  }
+
+  private rejectVersusTarget(target: ASTNode, token: Token): void {
+    // ? Versus produces a PF2e degree outcome — a terminal scalar, not a
+    //   valid input to dice count/sides/thresholds. Symmetric with
+    //   `rejectSuccessCountTarget`; wrappers like `floor(vs)+0` still
+    //   propagate `versusMetadata` via `mergeContext`, so this only blocks
+    //   `mergeMetaRolls` sites where metadata would silently vanish.
+    // ? Narrow unwrap: only `Grouped`. `Modifier`/`Sort`/`CritThreshold`
+    //   cannot wrap a `Versus` because `containsDicePool` does not recurse
+    //   into `Versus`, so each of those parsers rejects the wrap upstream.
+    const node = unwrapTransparent(target, ['Grouped']);
+    if (node.type === 'Versus') {
+      throw new ParseError(
+        `Versus cannot be used as a meta-expression`,
+        'NESTED_VERSUS',
+        token.position,
+        token,
+      );
+    }
+    // ! Single-sub-roll `Group` passthrough is the new sibling route —
+    //   `containsDicePool` recurses into Group's single sub-expression via
+    //   `deepContainsDicePool`, which traverses Versus's `roll`/`dc`. Deep
+    //   walk for any descendant Versus so `{1d20 vs 15}cs>18`,
+    //   `{1+(1d20 vs 15)}cs>18`, and `4d6>={abs(1d20 vs 15)}` reject too.
+    if (node.type === 'Group' && node.expressions.length === 1) {
+      const inner = node.expressions[0];
+      if (inner != null && containsVersus(inner)) {
+        throw new ParseError(
+          `Versus cannot be used as a meta-expression`,
+          'NESTED_VERSUS',
+          token.position,
+          token,
+        );
+      }
+    }
+  }
+
+  private parseModifier(target: ASTNode, token: Token): ModifierNode {
+    this.rejectSuccessCountTarget(target, token);
+    // ! Mirror `parseSort`/`parseCritThreshold` — keep/drop applied to a
+    //   Versus target silently drops `degree`/`natural` metadata. Pre-existing
+    //   for `(1d20 vs 15)kh1` (caught upstream by `containsDicePool` with a
+    //   different error code), but the single-sub-roll Group passthrough makes
+    //   `{1d20 vs 15}kh1` reachable past `containsDicePool` (Group's deep
+    //   walk recurses into Versus's roll/dc), so the explicit reject is the
+    //   only thing that closes the metadata-drop hole.
+    this.rejectVersusTarget(target, token);
+
+    // Keep/drop modifiers need a dice pool to select from. Wrapping arithmetic
+    // (e.g. `(1d6+5)kh1`, `4d6+2kh3`) would silently drop user math.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Keep/drop modifiers require a dice pool target`,
+        'INVALID_MODIFIER_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    const modifier =
+      token.type === TokenType.KEEP_HIGH || token.type === TokenType.KEEP_LOW ? 'keep' : 'drop';
+
+    const selector =
+      token.type === TokenType.KEEP_HIGH || token.type === TokenType.DROP_HIGH
+        ? 'highest'
+        : 'lowest';
+
+    // Default to 1 when no explicit count follows the modifier (e.g., 4d6kh → 4d6kh1)
+    const nextToken = this.peek().type;
+    const hasExplicitCount =
+      nextToken === TokenType.NUMBER ||
+      nextToken === TokenType.LPAREN ||
+      nextToken === TokenType.AT;
+    const count: ASTNode = hasExplicitCount
+      ? this.parseExpression(BP.DICE_LEFT)
+      : Parser.syntheticLiteral(1, token);
+    this.rejectSuccessCountTarget(count, token);
+    this.rejectVersusTarget(count, token);
+
+    return {
+      type: 'Modifier',
+      modifier,
+      selector,
+      count,
+      target,
+      start: target.start ?? token.position,
+      end: hasExplicitCount ? (count.end ?? token.end) : token.end,
+    };
+  }
+
+  private parseExplode(target: ASTNode, token: Token): ExplodeNode {
+    this.rejectSuccessCountTarget(target, token);
+
+    // Groups have no explode semantics — reject outright. Must come before
+    // `containsDicePool`, which recurses into `Group` and would otherwise
+    // let `{4d6}!` slip through.
+    this.rejectGroupTarget(target, token, 'explode', 'INVALID_EXPLODE_TARGET');
+
+    // Explode needs a dice pool to explode on. Wrapping arithmetic (e.g.
+    // `(1d6+5)!`, `floor(1d6/2)!`) would silently drop user math.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Explode modifier requires a dice pool target`,
+        'INVALID_EXPLODE_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // Fate dice (sides = 0) cannot explode — the symmetric -1/0/+1 range has
+    // no natural "max" trigger, so semantics are undefined. Reject at parse
+    // time rather than silently no-op in the evaluator.
+    if (containsFatePool(target)) {
+      throw new ParseError(
+        `Fate dice cannot explode`,
+        'INVALID_EXPLODE_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // ? Reject nested explodes (e.g., `1d6!!!`) — a second explode token atop
+    //   an ExplodeNode has no meaningful semantics and is rejected per spec.
+    if (target.type === 'Explode') {
+      throw new ParseError(
+        `Cannot chain explode modifiers`,
+        'INVALID_EXPLODE_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    const variant: ExplodeNode['variant'] =
+      token.type === TokenType.EXPLODE
+        ? 'standard'
+        : token.type === TokenType.EXPLODE_COMPOUND
+          ? 'compound'
+          : 'penetrating';
+
+    const node: ExplodeNode = {
+      type: 'Explode',
+      variant,
+      target,
+      start: target.start ?? token.position,
+      end: token.end,
+    };
+    if (this.isComparePointAhead()) {
+      node.threshold = this.parseComparePoint();
+      node.end = node.threshold.value.end ?? token.end;
+    }
+    return node;
+  }
+
+  private parseReroll(target: ASTNode, token: Token): RerollNode {
+    this.rejectSuccessCountTarget(target, token);
+
+    // Groups have no reroll semantics — reject outright. Must come before
+    // `containsDicePool`, which recurses into `Group`.
+    this.rejectGroupTarget(target, token, 'reroll', 'INVALID_REROLL_TARGET');
+
+    // Reroll needs a dice pool to inspect. Wrapping arithmetic (e.g.
+    // `(1d6+5)r<3`, `floor(1d6/2)ro<3`) would silently drop user math.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Reroll modifier requires a dice pool target`,
+        'INVALID_REROLL_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // A reroll token must be followed by a comparison — bare `r` / `ro` is invalid.
+    if (!this.isComparePointAhead()) {
+      throw new ParseError(
+        `Expected comparison operator after '${token.value}'`,
+        'EXPECTED_TOKEN',
+        token.position,
+        token,
+      );
+    }
+
+    const once = token.type === TokenType.REROLL_ONCE;
+    const condition = this.parseComparePoint();
+
+    return {
+      type: 'Reroll',
+      once,
+      condition,
+      target,
+      start: target.start ?? token.position,
+      end: condition.value.end ?? token.end,
+    };
+  }
+
+  private parseSort(target: ASTNode, token: Token): SortNode {
+    this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+
+    // Sort is purely visual but still needs a dice pool to reorder —
+    // `5s`, `(1+2)s`, or `floor(5)s` have no dice to touch. Uses the deep
+    // guard so arithmetic-wrapped pools like `(1d6+2d8)s` are accepted per
+    // Stage 3 spec, while pure literals/arithmetic reject.
+    if (!deepContainsDicePool(target)) {
+      throw new ParseError(
+        `Sort modifier requires a dice pool target`,
+        'INVALID_SORT_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // ! Multi-sub-roll groups (`{a, b}s`, `({a, b})s`) need hierarchical
+    //   sort per Stage 3 spec §3 (sort dice within each sub-roll, then sort
+    //   sub-rolls by total) — `evalSort` only flat-sorts, so accepting the
+    //   syntax would silently ship non-spec behaviour. Reject at parse time
+    //   until the deferred Stage 4 implementation lands. Single-sub Groups
+    //   keep passing through (the unwrap returns a `Group` with one
+    //   expression, which is the user's flat-pool escape hatch).
+    const base = unwrapTransparent(target, ['Grouped', 'Modifier', 'Sort', 'CritThreshold']);
+    if (base.type === 'Group' && base.expressions.length >= 2) {
+      throw new ParseError(
+        `Sort modifier does not yet support multi-sub-roll groups`,
+        'INVALID_SORT_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    const order: SortNode['order'] = token.type === TokenType.SORT_ASC ? 'ascending' : 'descending';
+
+    // ? Chained sorts (`4d6ss`, `4d6sasd`) are allowed — sort is idempotent
+    //   when repeated in the same direction; a later `sd` after `s` just
+    //   overrides the order since both pass over the same pool.
+    return {
+      type: 'Sort',
+      order,
+      target,
+      start: target.start ?? token.position,
+      end: token.end,
+    };
+  }
+
+  private parseCritThreshold(target: ASTNode, token: Token): CritThresholdNode {
+    this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+
+    // Multi-sub-roll groups have no crit-threshold semantics per Stage 3 spec
+    // — a group there is a container of sub-roll subtotals, not a dice pool,
+    // and applying cs/cf would override `critical`/`fumble` on dropped
+    // sub-roll dice. Single-sub-roll groups pass through under the documented
+    // flat-pool rule (`{1d20}kh1cs>18` ≡ `(1d20)kh1cs>18`). Must run before
+    // `containsDicePool`, which recurses into `Group`.
+    this.rejectGroupTarget(
+      target,
+      token,
+      'apply crit threshold to',
+      'INVALID_CRIT_THRESHOLD_TARGET',
+      true,
+    );
+
+    // Shallow dice-pool check (bare dice only) — rejects `(1d6+2d8)cs>5`,
+    // `5cs`, `(1+2)cs`, `floor(5)cs`. Matches explode/reroll behavior.
+    // Note: if `target` already is a `CritThresholdNode`, `containsDicePool`
+    // recurses into its `target`, so chained `cs`/`cf` naturally pass.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Crit threshold modifier requires a dice pool target`,
+        'INVALID_CRIT_THRESHOLD_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // Bare `cs`/`cf` resolve to a per-die default that assumes max-side / 1
+    // semantics — incompatible with Fate dice (`{-1, 0, +1}`), where the bare
+    // fumble check would flip the best face (`+1`) into a fumble. Custom
+    // thresholds with explicit ComparePoints remain accepted. Mirrors the
+    // Fate-explosion rejection above.
+    if (!this.isComparePointAhead() && containsFatePool(target)) {
+      throw new ParseError(
+        `Bare cs/cf cannot apply to Fate dice`,
+        'INVALID_CRIT_THRESHOLD_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    const threshold: CritThreshold = this.isComparePointAhead()
+      ? this.parseComparePoint()
+      : 'default';
+    const end = threshold === 'default' ? token.end : (threshold.value.end ?? token.end);
+
+    // ? Unwrap parens so `(1d20cs>19)cs=1` chains into the inner node. Without
+    //   unwrapping, the outer `cs` would create a second CritThresholdNode
+    //   wrapping the Grouped — the collapse-into-single-node design decision
+    //   from STAGE3.md §"CritThreshold Collects Multiple Thresholds" would
+    //   be subtly broken for any user who parenthesizes the chain.
+    let chainTarget: ASTNode = target;
+    while (chainTarget.type === 'Grouped') {
+      chainTarget = chainTarget.expression;
+    }
+    if (isCritThreshold(chainTarget)) {
+      if (token.type === TokenType.CRIT_SUCCESS) {
+        chainTarget.successThresholds.push(threshold);
+      } else {
+        chainTarget.failThresholds.push(threshold);
+      }
+      chainTarget.end = end;
+      return chainTarget;
+    }
+
+    return {
+      type: 'CritThreshold',
+      successThresholds: token.type === TokenType.CRIT_SUCCESS ? [threshold] : [],
+      failThresholds: token.type === TokenType.CRIT_FAIL ? [threshold] : [],
+      target,
+      start: target.start ?? token.position,
+      end,
+    };
+  }
+
+  private parseSuccessCount(target: ASTNode, token: Token): SuccessCountNode {
+    // Success counting is terminal: chaining (`>=5>=3`) has no semantics.
+    this.rejectSuccessCountTarget(target, token);
+
+    // Reject non-pool targets like `1>=3`, `(1+2)>=3`, `(1d6*2)>=10`, or
+    // `(1d20 vs 15)>=1`. Success counting operates on a raw dice pool; any
+    // arithmetic or composition wrapping would be silently ignored.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Success counting requires a dice pool target`,
+        'INVALID_SUCCESS_COUNT_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    const operator = this.getCompareOp(token);
+    // ? Threshold binding: `BP.DICE_LEFT` — see `parseComparePoint` JSDoc.
+    const value = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(value, token);
+    this.rejectVersusTarget(value, token);
+    const node: SuccessCountNode = {
+      type: 'SuccessCount',
+      target,
+      threshold: { operator, value },
+      start: target.start ?? token.position,
+      end: value.end ?? token.end,
+    };
+
+    if (this.peek().type === TokenType.FAIL) {
+      this.advance();
+      if (this.isComparePointAhead()) {
+        node.failThreshold = this.parseComparePoint();
+      } else {
+        // ? Same threshold binding as above (BP.DICE_LEFT).
+        const failValue = this.parseExpression(BP.DICE_LEFT);
+        this.rejectSuccessCountTarget(failValue, token);
+        this.rejectVersusTarget(failValue, token);
+        node.failThreshold = { operator: '=', value: failValue };
+      }
+      node.end = node.failThreshold.value.end ?? node.end ?? token.end;
+    }
+
+    return node;
+  }
+
+  private parseVersus(left: ASTNode, token: Token): VersusNode {
+    this.rejectSuccessCountTarget(left, token);
+
+    // ? Chained `a vs b vs c` has no semantics — a degree is a scalar, not a
+    //   comparable. Unwrap `Grouped` so `(a vs b) vs c` rejects at parse
+    //   time like the bare form; paren-nested DC (`a vs (b vs c)`) is still
+    //   caught by the evaluator via `mergeContext`.
+    let leftChain: ASTNode = left;
+    while (leftChain.type === 'Grouped') {
+      leftChain = leftChain.expression;
+    }
+    if (leftChain.type === 'Versus') {
+      throw new ParseError('Cannot chain versus operators', 'NESTED_VERSUS', token.position, token);
+    }
+
+    const dc = this.parseExpression(BP.VS_RIGHT);
+    this.rejectSuccessCountTarget(dc, token);
+
+    return {
+      type: 'Versus',
+      roll: left,
+      dc,
+      start: left.start ?? token.position,
+      end: dc.end ?? token.end,
+    };
+  }
+
+  // * Compare point utilities
+
+  /**
+   * Checks whether the next token is a comparison operator.
+   */
+  isComparePointAhead(): boolean {
+    const type = this.peek().type;
+    return (
+      type === TokenType.GREATER ||
+      type === TokenType.GREATER_EQUAL ||
+      type === TokenType.LESS ||
+      type === TokenType.LESS_EQUAL ||
+      type === TokenType.EQUAL
+    );
+  }
+
+  /**
+   * 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 {
+    const token = this.peek();
+    const operator = this.getCompareOp(token);
+
+    this.advance();
+
+    const value = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(value, token);
+    this.rejectVersusTarget(value, token);
+
+    return { operator, value };
+  }
+
+  private getCompareOp(token: Token): CompareOp {
+    switch (token.type) {
+      case TokenType.GREATER:
+        return '>';
+      case TokenType.GREATER_EQUAL:
+        return '>=';
+      case TokenType.LESS:
+        return '<';
+      case TokenType.LESS_EQUAL:
+        return '<=';
+      case TokenType.EQUAL:
+        return '=';
+      default:
+        throw new ParseError(
+          `Expected comparison operator but got '${token.value}'`,
+          'EXPECTED_TOKEN',
+          token.position,
+          token,
+        );
+    }
+  }
+
+  // * Helpers
+
+  private getOperatorSymbol(token: Token): '+' | '-' | '*' | '/' | '%' | '**' {
+    switch (token.type) {
+      case TokenType.PLUS:
+        return '+';
+      case TokenType.MINUS:
+        return '-';
+      case TokenType.MULTIPLY:
+        return '*';
+      case TokenType.DIVIDE:
+        return '/';
+      case TokenType.MODULO:
+        return '%';
+      case TokenType.POWER:
+        return '**';
+      default:
+        throw new ParseError(
+          `Unknown operator '${token.value}'`,
+          'UNEXPECTED_TOKEN',
+          token.position,
+          token,
+        );
+    }
+  }
+
+  private getLeftBp(token: Token): number {
+    switch (token.type) {
+      case TokenType.VS:
+        return BP.VS_LEFT;
+      case TokenType.PLUS:
+      case TokenType.MINUS:
+        return BP.ADD_LEFT;
+      case TokenType.MULTIPLY:
+      case TokenType.DIVIDE:
+      case TokenType.MODULO:
+        return BP.MUL_LEFT;
+      case TokenType.POWER:
+        return BP.POW_LEFT;
+      case TokenType.DICE:
+      case TokenType.DICE_PERCENT:
+      case TokenType.DICE_FATE:
+        return BP.DICE_LEFT;
+      case TokenType.KEEP_HIGH:
+      case TokenType.KEEP_LOW:
+      case TokenType.DROP_HIGH:
+      case TokenType.DROP_LOW:
+      case TokenType.EXPLODE:
+      case TokenType.EXPLODE_COMPOUND:
+      case TokenType.EXPLODE_PENETRATING:
+      case TokenType.REROLL:
+      case TokenType.REROLL_ONCE:
+      case TokenType.SORT_ASC:
+      case TokenType.SORT_DESC:
+      case TokenType.CRIT_SUCCESS:
+      case TokenType.CRIT_FAIL:
+        return BP.MODIFIER;
+      // Comparison operators act as LED-dispatched success-count modifiers
+      // at the Pratt level. Sit below ADD/MUL so arithmetic on a dice pool
+      // completes before success counting wraps it — `5d6+2>4` parses as
+      // `(5d6+2)>4` and then cleanly fails the pool-target guard, rather
+      // than the `>` stealing `2` from the `+`. Inside `parseComparePoint`
+      // (called manually by explode/reroll) this BP is bypassed.
+      case TokenType.GREATER:
+      case TokenType.GREATER_EQUAL:
+      case TokenType.LESS:
+      case TokenType.LESS_EQUAL:
+      case TokenType.EQUAL:
+        return BP.COMPARE;
+      case TokenType.RPAREN:
+      case TokenType.EOF:
+      // Punctuation and keywords that terminate expressions
+      case TokenType.COMMA:
+      case TokenType.FUNCTION:
+      // Group boundaries: `}` closes the current group (consumed inside
+      // `parseGroup`), and a stray `{` after a complete expression is an
+      // error. Both terminate the outer Pratt loop at -1.
+      case TokenType.LBRACE:
+      case TokenType.RBRACE:
+        return -1;
+      default:
+        return 0;
+    }
+  }
+
+  private getRightBp(token: Token): number {
+    switch (token.type) {
+      case TokenType.VS:
+        return BP.VS_RIGHT;
+      case TokenType.PLUS:
+      case TokenType.MINUS:
+        return BP.ADD_RIGHT;
+      case TokenType.MULTIPLY:
+      case TokenType.DIVIDE:
+      case TokenType.MODULO:
+        return BP.MUL_RIGHT;
+      case TokenType.POWER:
+        return BP.POW_RIGHT;
+      case TokenType.DICE:
+        return BP.DICE_RIGHT;
+      default:
+        return 0;
+    }
+  }
+
+  private peek(): Token {
+    return (
+      this.tokens[this.pos] ?? { type: TokenType.EOF, value: '', position: this.pos, end: this.pos }
+    );
+  }
+
+  private advance(): Token {
+    const token = this.peek();
+    this.pos++;
+    return token;
+  }
+
+  private expect(type: TokenType): Token {
+    const token = this.peek();
+    if (token.type !== type) {
+      const expected = TOKEN_DISPLAY[type] ?? TokenType[type];
+      const got = token.type === TokenType.EOF ? 'end of input' : `'${token.value}'`;
+      throw new ParseError(
+        `Expected ${expected} but got ${got}`,
+        'EXPECTED_TOKEN',
+        token.position,
+        token,
+      );
+    }
+    return this.advance();
+  }
+
+  private hasTokens(): boolean {
+    return this.peek().type !== TokenType.EOF;
+  }
+}
+
+/**
+ * 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 function parse(notation: string): ASTNode {
+  const tokens = lex(notation);
+  const parser = new Parser(tokens);
+  return parser.parse();
+}