roll-parser 3.2.2 → 3.3.1

package/src/evaluator/modifiers/flags.ts

@@ -68,11 +68,27 @@ export function stripFlags(
   return modifiers.filter((modifier) => !excluded.includes(modifier));
 }
 
-/** Returns `modifiers` with `excluded` removed and `added` appended, in order. */
+/**
+ * Returns `modifiers` with `excluded` removed and `added` appended, in order.
+ *
+ * ! Always a fresh array. `mergeMetaRolls` clones a die as
+ * ! `{ ...die, modifiers: rewriteFlags(...) }`, so returning the input when it
+ * ! already matches would leave clone and original sharing mutated flags.
+ */
 export function rewriteFlags(
   modifiers: readonly DieModifier[],
   excluded: readonly DieModifier[],
   ...added: DieModifier[]
 ): DieModifier[] {
-  return [...stripFlags(modifiers, excluded), ...added];
+  // One array, not `stripFlags`'s filter plus a spread — this runs per die.
+  const rewritten: DieModifier[] = [];
+
+  for (const modifier of modifiers) {
+    if (!excluded.includes(modifier)) rewritten.push(modifier);
+  }
+  for (const flag of added) {
+    rewritten.push(flag);
+  }
+
+  return rewritten;
 }

package/src/lexer/lexer.ts

@@ -41,6 +41,9 @@ export class LexerError extends RollParserError {
    * 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`.
+   *
+   * Not guaranteed to appear in `message` — errors that name a rule rather than
+   * a character leave it out.
    */
   readonly character: string;
 
@@ -51,7 +54,7 @@ export class LexerError extends RollParserError {
     character: string,
     options?: ErrorOptions,
   ) {
-    super(`${message}: '${character}'`, code, options);
+    super(message, code, options);
     this.name = 'LexerError';
     this.position = position;
     this.character = character;
@@ -71,8 +74,14 @@ 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> = {
+/**
+ * Known identifier keywords mapped to their token types.
+ *
+ * Null-prototype, because every lookup here is keyed by arbitrary user input.
+ * Over a plain object literal `'constructor'` resolves to `Object`'s own, and
+ * the identifier leaves the lexer as a token whose `type` is a function.
+ */
+const IDENTIFIER_KEYWORDS: Record<string, TokenType> = Object.assign(Object.create(null), {
   kh: TokenType.KEEP_HIGH,
   kl: TokenType.KEEP_LOW,
   k: TokenType.KEEP_HIGH,
@@ -96,20 +105,58 @@ const IDENTIFIER_KEYWORDS: Record<string, TokenType> = {
   sd: TokenType.SORT_DESC,
   cs: TokenType.CRIT_SUCCESS,
   cf: TokenType.CRIT_FAIL,
-};
+} satisfies Record<string, TokenType>);
+
+/**
+ * Dice-pool modifiers that maximal munch can merge, mapped to what re-separates
+ * them: a count for the ones that take an operand, a space for the ones that do
+ * not. Membership doubles as the filter — the keywords left out (`d`, `f`, `r`,
+ * `ro`, `vs`, the function names) have no split that parses.
+ */
+// ! `min`/`max` share `TokenType.FUNCTION` with `floor`, so the separator
+// ! cannot be derived from the token type. Null-prototype for the same reason
+// ! as `IDENTIFIER_KEYWORDS` above.
+const MODIFIER_SEPARATORS: Record<string, string> = Object.assign(Object.create(null), {
+  kh: '1',
+  kl: '1',
+  k: '1',
+  dh: '1',
+  dl: '1',
+  min: '1',
+  max: '1',
+  s: ' ',
+  sa: ' ',
+  sd: ' ',
+  cs: ' ',
+  cf: ' ',
+} satisfies Record<string, string>);
+
+/**
+ * Names a code point the message cannot render — a no-break space, zero-width
+ * space or byte-order mark shows as nothing between the quotes. Printable ASCII
+ * is legible there already and stays unadorned.
+ */
+function nameCodePoint(codePoint: number | undefined): string {
+  if (codePoint == null || (codePoint > 0x20 && codePoint < 0x7f)) return '';
+  return ` (U+${codePoint.toString(16).toUpperCase().padStart(4, '0')})`;
+}
 
 /**
- * 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.
+ * Builds a hint for identifiers that merged two modifiers. Maximal munch joins
+ * them when the first takes no count — `4d6khs` lexes as one identifier `khs`
+ * instead of `kh` + `s` — so the fix is to re-separate them.
+ *
+ * Both halves must be separable: `flor` and `kx` start with a keyword but end
+ * in something no split can rescue, so they get no hint.
  */
 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 separator = MODIFIER_SEPARATORS[prefix];
+    if (separator == 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}')`;
+    if (MODIFIER_SEPARATORS[rest] == null) continue;
+    return ` (did you mean '${prefix}' followed by '${rest}'? write it as '${prefix}${separator}${rest}')`;
   }
   return '';
 }
@@ -221,7 +268,12 @@ export class Lexer {
         // 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);
+        throw new LexerError(
+          `Unexpected character${nameCodePoint(codePoint)}: '${display}'`,
+          'UNEXPECTED_CHARACTER',
+          startPos,
+          display,
+        );
       }
     }
   }
@@ -294,7 +346,7 @@ export class Lexer {
     }
 
     throw new LexerError(
-      `Unexpected identifier${buildIdentifierHint(lower)}`,
+      `Unexpected identifier${buildIdentifierHint(lower)}: '${lower}'`,
       'UNEXPECTED_IDENTIFIER',
       startPos,
       lower,
@@ -332,7 +384,15 @@ export class Lexer {
     } else {
       const nameStart = this.pos;
       if (this.isAtEnd() || !this.isIdentifierStart(this.peek())) {
-        throw new LexerError('Empty @ variable name', 'UNEXPECTED_CHARACTER', startPos, '@');
+        // Reached by a missing name and by one starting with a digit or a
+        // non-ASCII letter alike, so the message names the rule rather than
+        // any one of those causes.
+        throw new LexerError(
+          `@ variable name must start with a letter or '_'`,
+          'UNEXPECTED_CHARACTER',
+          startPos,
+          '@',
+        );
       }
       this.advance();
       while (!this.isAtEnd() && this.isIdentifierPart(this.peek())) {

package/src/parser/parser.ts

@@ -172,6 +172,55 @@ const TOKEN_DISPLAY = {
 /** Token types that carry a display symbol and may be passed to `expect()`. */
 type ExpectableToken = keyof typeof TOKEN_DISPLAY;
 
+/**
+ * True while a crit threshold carries only the bare `cs`/`cf` sentinel, so no
+ * comparison was consumed. Emptiness cannot answer this — bare `cs` fills the
+ * list with `'default'` rather than leaving it empty.
+ */
+function isBareCritThreshold(node: CritThresholdNode): boolean {
+  const isDefault = (threshold: CritThreshold): boolean => threshold === 'default';
+  return node.successThresholds.every(isDefault) && node.failThresholds.every(isDefault);
+}
+
+/**
+ * Follows a node down to the one whose source text the next token abuts.
+ *
+ * In `1+2d6s1` the sort is already buried under the `+` by the time the stray
+ * `1` reaches LED position.
+ *
+ * ! Only these three descend. Every other node that holds a sub-expression
+ * ! closes it first — `(…)`, `{…}`, `f(…)`, and the parenthesized operand of
+ * ! `2d(…)` or `4d6kh(…)` all put a delimiter between the child and the stray
+ * ! token, so the child is not what that token follows.
+ */
+function rightmostNode(node: ASTNode): ASTNode {
+  let current = node;
+  for (;;) {
+    switch (current.type) {
+      case 'BinaryOp':
+        current = current.right;
+        break;
+      case 'UnaryOp':
+        current = current.operand;
+        break;
+      case 'Versus':
+        current = current.dc;
+        break;
+      default:
+        return current;
+    }
+  }
+}
+
+/**
+ * Names the operand a token was still waiting for when the notation ran out.
+ */
+function expectedOperand(token: Token): string {
+  if (token.type === TokenType.DICE) return 'a side count';
+  if (token.type === TokenType.VS) return 'a difficulty class';
+  return 'a value';
+}
+
 /**
  * Arity table for math functions. `min` and `max` are inclusive.
  * `POSITIVE_INFINITY` means unbounded (variadic).
@@ -220,11 +269,9 @@ export class Parser {
    * 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);
+    // Nothing has demanded an operand yet, so an immediate EOF is an empty
+    // notation rather than a truncated one.
+    const ast = this.parseExpression(0, undefined);
 
     if (this.peek().type !== TokenType.EOF) {
       const token = this.peek();
@@ -241,14 +288,18 @@ export class Parser {
 
   /**
    * Parse an expression with minimum binding power.
+   *
+   * `pending` is the token that demanded this operand — the `d` of `1d`, the
+   * `<` of `2d6r<`. It exists so a truncated notation can name what it was
+   * waiting for; `undefined` only at the top of the input.
    */
-  private parseExpression(minBp: number): ASTNode {
+  private parseExpression(minBp: number, pending: Token | undefined): ASTNode {
     const entryDepth = this.depth;
     this.depth += 1;
     this.guardDepth();
 
     try {
-      let left = this.parseNud();
+      let left = this.parseNud(pending);
 
       while (this.hasTokens()) {
         const token = this.peek();
@@ -290,7 +341,7 @@ export class Parser {
    * NUD - Null Denotation.
    * Handles tokens that appear at the start of an expression (prefix position).
    */
-  private parseNud(): ASTNode {
+  private parseNud(pending: Token | undefined): ASTNode {
     const token = this.advance();
 
     switch (token.type) {
@@ -322,7 +373,23 @@ export class Parser {
         return this.parseVariable(token);
 
       case TokenType.EOF:
-        throw new ParseError('Unexpected end of input', 'UNEXPECTED_END', token.position);
+        throw new ParseError(
+          pending == null
+            ? 'Empty notation'
+            : `Expected ${expectedOperand(pending)} after '${pending.value}'`,
+          'UNEXPECTED_END',
+          token.position,
+        );
+
+      // Reaching prefix position means no roll precedes the `vs`, so there is
+      // nothing to check against the DC.
+      case TokenType.VS:
+        throw new ParseError(
+          'Versus needs a roll on its left',
+          'UNEXPECTED_TOKEN',
+          token.position,
+          token,
+        );
 
       default:
         throw new ParseError(
@@ -398,13 +465,32 @@ export class Parser {
       case TokenType.FAIL:
         return Parser.throwOrphanFailThreshold(token);
 
-      default:
+      default: {
+        // A bare number after a modifier that took none — `2d6s1`, `2d6!0`.
+        // ! Only while the modifier is still empty-handed: past `2d6!>1 2` the
+        // ! explode did take its comparison, and the stray number is an
+        // ! unrelated juxtaposition that keeps the generic message.
+        const trailing = rightmostNode(left);
+        if (
+          token.type === TokenType.NUMBER &&
+          (trailing.type === 'Sort' ||
+            (trailing.type === 'Explode' && trailing.threshold == null) ||
+            (trailing.type === 'CritThreshold' && isBareCritThreshold(trailing)))
+        ) {
+          throw new ParseError(
+            'This modifier takes no count',
+            'UNEXPECTED_TOKEN',
+            token.position,
+            token,
+          );
+        }
         throw new ParseError(
           `Unexpected infix token '${token.value}'`,
           'UNEXPECTED_TOKEN',
           token.position,
           token,
         );
+      }
     }
   }
 
@@ -430,7 +516,7 @@ export class Parser {
   }
 
   private parseUnaryMinus(token: Token): UnaryOpNode {
-    const operand = this.parseExpression(BP.UNARY);
+    const operand = this.parseExpression(BP.UNARY, token);
     this.rejectSuccessCountTarget(operand, token);
     return {
       type: 'UnaryOp',
@@ -442,7 +528,7 @@ export class Parser {
   }
 
   private parsePrefixDice(token: Token): DiceNode {
-    const sides = this.parseExpression(BP.DICE_RIGHT);
+    const sides = this.parseExpression(BP.DICE_RIGHT, token);
     this.rejectSuccessCountTarget(sides, token);
     this.rejectVersusMetaOperand(sides, token);
     return {
@@ -458,7 +544,7 @@ export class Parser {
     this.rejectSuccessCountTarget(left, token);
     this.rejectVersusMetaOperand(left, token);
     this.rejectBareDiceChain(left, token);
-    const sides = this.parseExpression(BP.DICE_RIGHT);
+    const sides = this.parseExpression(BP.DICE_RIGHT, token);
     this.rejectSuccessCountTarget(sides, token);
     this.rejectVersusMetaOperand(sides, token);
     return {
@@ -517,7 +603,13 @@ export class Parser {
   }
 
   private parseGrouped(token: Token): GroupedNode {
-    const expression = this.parseExpression(0);
+    // Mirrors `parseGroup`'s empty check; without it `)` reaches the prefix arm
+    // and reports itself, naming the closer rather than the empty construct.
+    if (this.peek().type === TokenType.RPAREN) {
+      throw new ParseError('Empty parentheses', 'UNEXPECTED_TOKEN', token.position, token);
+    }
+
+    const expression = this.parseExpression(0, token);
     const close = this.expect(TokenType.RPAREN);
     return { type: 'Grouped', expression, start: token.position, end: close.end };
   }
@@ -530,10 +622,10 @@ export class Parser {
       throw new ParseError('Empty group', 'UNEXPECTED_TOKEN', startToken.position, startToken);
     }
 
-    const expressions: ASTNode[] = [this.parseExpression(0)];
+    const expressions: ASTNode[] = [this.parseExpression(0, startToken)];
     while (this.peek().type === TokenType.COMMA) {
-      this.advance();
-      expressions.push(this.parseExpression(0));
+      const comma = this.advance();
+      expressions.push(this.parseExpression(0, comma));
     }
 
     if (this.peek().type !== TokenType.RBRACE) {
@@ -557,16 +649,16 @@ export class Parser {
   private parseFunctionCall(token: Token): FunctionCallNode {
     // `FUNCTION`, `COMMA`, and `RPAREN` all sit at BP -1, so argument boundaries
     // fall out of the inner `parseExpression(0)` calls terminating on their own.
-    this.expect(TokenType.LPAREN);
+    const open = this.expect(TokenType.LPAREN);
 
     const args: ASTNode[] = [];
     if (this.peek().type !== TokenType.RPAREN) {
-      const first = this.parseExpression(0);
+      const first = this.parseExpression(0, open);
       this.rejectSuccessCountTarget(first, token);
       args.push(first);
       while (this.peek().type === TokenType.COMMA) {
-        this.advance();
-        const next = this.parseExpression(0);
+        const comma = this.advance();
+        const next = this.parseExpression(0, comma);
         this.rejectSuccessCountTarget(next, token);
         args.push(next);
       }
@@ -610,7 +702,7 @@ export class Parser {
 
     const operator = this.getOperatorSymbol(token);
     const rightBp = this.getRightBp(token);
-    const right = this.parseExpression(rightBp);
+    const right = this.parseExpression(rightBp, token);
 
     this.rejectSuccessCountTarget(right, token);
 
@@ -659,8 +751,12 @@ export class Parser {
     // never hide inside one and widening the set would never match.
     const node = unwrapGrouped(target);
     if (isSuccessCount(node)) {
+      // ! Three shapes reach here and only one is a modifier — arithmetic
+      // ! (`5d6>=5+3`) and meta-operand reuse (`4d(1d6>=3)`) do too, so the
+      // ! message has to stay true of all three. **README.md → Pools and
+      // ! checks** carries the worked rewrites.
       throw new ParseError(
-        `Cannot apply modifier after success counting`,
+        `Success counting is terminal: it cannot be part of a larger expression`,
         'INVALID_SUCCESS_COUNT_TARGET',
         token.position,
         token,
@@ -820,7 +916,7 @@ export class Parser {
       nextToken === TokenType.LPAREN ||
       nextToken === TokenType.AT;
     const count: ASTNode = hasExplicitCount
-      ? this.parseExpression(BP.DICE_LEFT)
+      ? this.parseExpression(BP.DICE_LEFT, token)
       : Parser.syntheticLiteral(1, token);
     this.rejectSuccessCountTarget(count, token);
     this.rejectVersusMetaOperand(count, token);
@@ -982,7 +1078,7 @@ export class Parser {
       );
     }
 
-    const value = this.parseExpression(BP.DICE_LEFT);
+    const value = this.parseExpression(BP.DICE_LEFT, token);
     this.rejectSuccessCountTarget(value, token);
     this.rejectVersusMetaOperand(value, token);
 
@@ -1156,7 +1252,7 @@ export class Parser {
 
     const operator = this.getCompareOp(token);
     // Threshold binds at `BP.DICE_LEFT` — see `parseComparePoint` TSDoc.
-    const value = this.parseExpression(BP.DICE_LEFT);
+    const value = this.parseExpression(BP.DICE_LEFT, token);
     this.rejectSuccessCountTarget(value, token);
     this.rejectVersusMetaOperand(value, token);
     const start = target.start ?? token.position;
@@ -1166,8 +1262,8 @@ export class Parser {
       return { type: 'SuccessCount', target, threshold: { operator, value }, start, end };
     }
 
-    this.advance();
-    const failThreshold = this.parseFailThreshold(token);
+    const failToken = this.advance();
+    const failThreshold = this.parseFailThreshold(token, failToken);
 
     return {
       type: 'SuccessCount',
@@ -1179,12 +1275,18 @@ export class Parser {
     };
   }
 
-  /** Parses the `f...` suffix of a success count. Bare `fN` means `f=N`. */
-  private parseFailThreshold(token: Token): ComparePoint {
+  /**
+   * Parses the `f...` suffix of a success count. Bare `fN` means `f=N`.
+   *
+   * `token` is the success-count comparison, which the reject calls report
+   * against; `failToken` is the `f`, so a truncated `2d6>=4f` names it rather
+   * than the comparison behind it.
+   */
+  private parseFailThreshold(token: Token, failToken: Token): ComparePoint {
     if (this.isComparePointAhead()) return this.parseComparePoint();
 
     // Same threshold binding as `parseComparePoint` (BP.DICE_LEFT).
-    const failValue = this.parseExpression(BP.DICE_LEFT);
+    const failValue = this.parseExpression(BP.DICE_LEFT, failToken);
     this.rejectSuccessCountTarget(failValue, token);
     this.rejectVersusMetaOperand(failValue, token);
 
@@ -1226,7 +1328,7 @@ export class Parser {
       throw new ParseError('Cannot chain versus operators', 'NESTED_VERSUS', token.position, token);
     }
 
-    const dc = this.parseExpression(BP.VS_RIGHT);
+    const dc = this.parseExpression(BP.VS_RIGHT, token);
     this.rejectSuccessCountTarget(dc, token);
 
     return {
@@ -1276,7 +1378,7 @@ export class Parser {
 
     this.advance();
 
-    const value = this.parseExpression(BP.DICE_LEFT);
+    const value = this.parseExpression(BP.DICE_LEFT, token);
     this.rejectSuccessCountTarget(value, token);
     this.rejectVersusMetaOperand(value, token);
 

package/src/render.ts

@@ -342,8 +342,9 @@ function renderGroup(
   plain: boolean,
 ): string {
   const { keptIndices } = part;
+  const kept = keptIndices == null ? null : new Set(keptIndices);
   const subRolls = part.parts.map((sub, index) => {
-    if (keptIndices == null || keptIndices.includes(index)) {
+    if (kept == null || kept.has(index)) {
       return renderPart(sub, marks, plain);
     }
     const inner = renderPart(sub, marks, true);

package/src/rng/seeded.ts

@@ -246,6 +246,10 @@ export class SeededRNG implements RNG {
    */
   private toSeedString(seed?: string | number): string {
     // ! The library's one permitted `Math.random()` site — both draws stay here.
+    // ! Decimal double-to-string is a JIT fast path and other radixes are not, so
+    // ! every shorter encoding measured slower despite the shorter `hashSeed` loop.
+    // ! Only truncating each draw to a uint32 beats it, at 64 draw bits against the
+    // ! ~100 documented above. A faster auto-seed must skip the string, not shorten it.
     if (seed == null) return `${Date.now()}-${Math.random()}-${Math.random()}`;
     return String(seed);
   }

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by `bun run generate:version` from package.json — do not edit.
-export const version = '3.2.2';
+export const version = '3.3.1';