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

package/dist/testing.js

@@ -36,3 +36,6 @@ export {
   createMockRng2 as createMockRng,
   MockRNGExhaustedError2 as MockRNGExhaustedError
 };
+
+//# debugId=916ECEA68894E64864756E2164756E21
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/rng/mock.ts", "../src/testing.ts"],
+  "sourcesContent": [
+    "/**\n * Mock RNG for deterministic testing.\n *\n * @module rng/mock\n */\n\nimport type { RNG } from './types.js';\n\n/**\n * Error thrown when MockRNG exhausts its predefined values.\n *\n * This is intentional behavior to catch incorrect roll counts in tests.\n * If you see this error, your test is consuming more random values than expected.\n */\nexport class MockRNGExhaustedError extends Error {\n  readonly consumed: number;\n\n  constructor(consumed: number) {\n    super(`MockRNG exhausted: consumed ${consumed} values, no more available`);\n    this.name = 'MockRNGExhaustedError';\n    this.consumed = consumed;\n  }\n}\n\n/**\n * Creates a mock RNG that returns predefined values in sequence.\n *\n * IMPORTANT: Throws MockRNGExhaustedError when all values are consumed.\n * This behavior catches incorrect roll counts in tests - it never wraps around.\n *\n * @param values - Array of values to return (dice results for nextInt, floats for next)\n * @returns RNG instance returning predefined values\n *\n * @example\n * ```typescript\n * const rng = createMockRng([4, 2, 6]);\n * rng.nextInt(1, 6);  // Returns 4\n * rng.nextInt(1, 6);  // Returns 2\n * rng.nextInt(1, 6);  // Returns 6\n * rng.nextInt(1, 6);  // Throws MockRNGExhaustedError\n * ```\n */\nexport function createMockRng(values: number[]): RNG {\n  let index = 0;\n\n  const getNext = (): number => {\n    const value = values[index];\n    if (value === undefined) {\n      throw new MockRNGExhaustedError(index);\n    }\n    index++;\n    return value;\n  };\n\n  return {\n    next: getNext,\n    nextInt: (min: number, max: number): number => {\n      const value = getNext();\n      if (value < min || value > max) {\n        throw new RangeError(`MockRNG value ${value} is out of bounds [${min}, ${max}]`);\n      }\n      return value;\n    },\n  };\n}\n",
+    "/**\n * Test utilities for roll-parser consumers.\n *\n * Import from `roll-parser/testing` for deterministic dice testing.\n *\n * @module testing\n */\n\n// Direct value exports force the bundler to inline the code\nimport {\n  MockRNGExhaustedError as _MockRNGExhaustedError,\n  createMockRng as _createMockRng,\n} from './rng/mock.js';\n\nexport const createMockRng = _createMockRng;\nexport const MockRNGExhaustedError = _MockRNGExhaustedError;\n"
+  ],
+  "mappings": ";AAcO,MAAM,8BAA8B,MAAM;AAAA,EACtC;AAAA,EAET,WAAW,CAAC,UAAkB;AAAA,IAC5B,MAAM,+BAA+B,oCAAoC;AAAA,IACzE,KAAK,OAAO;AAAA,IACZ,KAAK,WAAW;AAAA;AAEpB;AAoBO,SAAS,aAAa,CAAC,QAAuB;AAAA,EACnD,IAAI,QAAQ;AAAA,EAEZ,MAAM,UAAU,MAAc;AAAA,IAC5B,MAAM,QAAQ,OAAO;AAAA,IACrB,IAAI,UAAU,WAAW;AAAA,MACvB,MAAM,IAAI,sBAAsB,KAAK;AAAA,IACvC;AAAA,IACA;AAAA,IACA,OAAO;AAAA;AAAA,EAGT,OAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS,CAAC,KAAa,QAAwB;AAAA,MAC7C,MAAM,QAAQ,QAAQ;AAAA,MACtB,IAAI,QAAQ,OAAO,QAAQ,KAAK;AAAA,QAC9B,MAAM,IAAI,WAAW,iBAAiB,2BAA2B,QAAQ,MAAM;AAAA,MACjF;AAAA,MACA,OAAO;AAAA;AAAA,EAEX;AAAA;;;ACjDK,IAAM,iBAAgB;AACtB,IAAM,yBAAwB;",
+  "debugId": "916ECEA68894E64864756E2164756E21",
+  "names": []
+}

package/dist/types.d.ts

@@ -3,7 +3,7 @@
  *
  * @module types
  */
-import type { ASTNode } from './parser/ast';
+import type { ASTNode } from './parser/ast.js';
 /**
  * Comparison operator for compare points.
  */
@@ -18,10 +18,23 @@ export type ComparePoint = {
     operator: CompareOp;
     value: ASTNode;
 };
+/**
+ * A ComparePoint whose value has been evaluated to a number. Used in
+ * `RollPart` where meta-expressions are already resolved.
+ */
+export type ResolvedComparePoint = {
+    operator: CompareOp;
+    value: number;
+};
+/**
+ * A resolved crit threshold — `'default'` means the per-die default rule
+ * (`result === sides` for critical, `result === 1` for fumble).
+ */
+export type ResolvedCritThreshold = ResolvedComparePoint | 'default';
 /**
  * Modifier flags applied to individual die results.
  */
-export type DieModifier = 'dropped' | 'kept' | 'exploded' | 'rerolled' | 'success' | 'failure';
+export type DieModifier = 'dropped' | 'kept' | 'exploded' | 'rerolled' | 'success' | 'failure' | 'meta';
 /**
  * PF2e Degree of Success. Produced by the `vs` operator when comparing a
  * roll against a Difficulty Class. Ordering is significant — natural 20
@@ -45,6 +58,13 @@ export type DieResult = {
     sides: number;
     /** The rolled value */
     result: number;
+    /**
+     * Raw first roll before any mutation (e.g., compound-explode accumulation).
+     * Only populated when `result` has been overwritten with a computed value.
+     * Consumers that need the original face (nat-20 / nat-1 detection) should
+     * read `initialResult ?? result`.
+     */
+    initialResult?: number;
     /** Modifiers applied to this die */
     modifiers: DieModifier[];
     /** True if rolled the maximum value (always false for Fate dice) */
@@ -52,6 +72,120 @@ export type DieResult = {
     /** True if rolled 1 (always false for Fate dice) */
     fumble: boolean;
 };
+/**
+ * Per-spec keep/drop entry inside a flattened modifier chain. Counts are
+ * resolved at evaluation time (meta-expressions like `kh(1d2)` become the
+ * rolled number).
+ */
+export type ModifierSpec = {
+    kind: 'keep' | 'drop';
+    selector: 'highest' | 'lowest';
+    count: number;
+};
+/**
+ * Fields shared by every RollPart variant. `start`/`end` mirror the source
+ * span of the AST node the part was evaluated from — present whenever the
+ * AST came from `parse()`, absent on hand-built ASTs.
+ */
+type RollPartBase = {
+    /** Sub-total this part contributed to its parent. */
+    total: number;
+    start?: number;
+    end?: number;
+};
+/**
+ * Structured breakdown of an evaluated expression, mirroring the AST 1:1 —
+ * every ASTNode produces exactly one RollPart. Discriminants are lowercase
+ * camelCase to distinguish evaluation-tree types from `ASTNode.type`
+ * (PascalCase) at a glance.
+ *
+ * Invariants:
+ * - `RollResult.parts.total === RollResult.total`.
+ * - `successCount.total === successes - failures`.
+ * - `literal.total === value` and `variable.total === value`.
+ * - Each part's `rolls[]` shares `DieResult` references with
+ *   `RollResult.rolls[]`; both reflect post-evaluation state (explode
+ *   accumulation, reroll flags, keep/drop flags). No deep clone.
+ *
+ * Meta-expression sub-trees (`4d6kh(1d2)`, `(1+1)d6` counts/sides, computed
+ * thresholds) are not surfaced as nested parts — their resolved numbers
+ * appear in the owning part, and their dice are inspectable in
+ * `RollResult.rolls` via the `'meta'` modifier tag.
+ */
+export type RollPart = (RollPartBase & {
+    type: 'literal';
+    value: number;
+}) | (RollPartBase & {
+    type: 'variable';
+    name: string;
+    value: number;
+}) | (RollPartBase & {
+    type: 'dice';
+    count: number;
+    sides: number;
+    rolls: DieResult[];
+}) | (RollPartBase & {
+    type: 'fateDice';
+    count: number;
+    rolls: DieResult[];
+}) | (RollPartBase & {
+    type: 'grouped';
+    inner: RollPart;
+}) | (RollPartBase & {
+    type: 'binaryOp';
+    operator: '+' | '-' | '*' | '/' | '%' | '**';
+    left: RollPart;
+    right: RollPart;
+}) | (RollPartBase & {
+    type: 'unaryOp';
+    operator: '-';
+    operand: RollPart;
+}) | (RollPartBase & {
+    type: 'modifier';
+    specs: ModifierSpec[];
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'explode';
+    variant: 'standard' | 'compound' | 'penetrating';
+    threshold?: ResolvedComparePoint;
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'reroll';
+    once: boolean;
+    condition: ResolvedComparePoint;
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'successCount';
+    threshold: ResolvedComparePoint;
+    failThreshold?: ResolvedComparePoint;
+    target: RollPart;
+    successes: number;
+    failures: number;
+}) | (RollPartBase & {
+    type: 'versus';
+    roll: RollPart;
+    dc: RollPart;
+    degree: DegreeOfSuccess;
+}) | (RollPartBase & {
+    type: 'functionCall';
+    name: string;
+    args: RollPart[];
+}) | (RollPartBase & {
+    type: 'group';
+    parts: RollPart[];
+    keptIndices?: number[];
+}) | (RollPartBase & {
+    type: 'sort';
+    order: 'ascending' | 'descending';
+    target: RollPart;
+}) | (RollPartBase & {
+    type: 'critThreshold';
+    successThresholds: ResolvedCritThreshold[];
+    failThresholds: ResolvedCritThreshold[];
+    target: RollPart;
+});
+/** Convenience alias for consumers writing exhaustive switches. */
+export type RollPartType = RollPart['type'];
 /**
  * Complete roll result with all metadata.
  */
@@ -66,6 +200,8 @@ export type RollResult = {
     rendered: string;
     /** All individual die results */
     rolls: DieResult[];
+    /** Structured breakdown of the evaluated expression, mirroring the AST 1:1. */
+    parts: RollPart;
     /**
      * Number of dice tagged as success across the whole expression. Present
      * only when a success-counting modifier was used. Independent of `total` —
@@ -101,5 +237,10 @@ export type EvaluateOptions = {
     maxExplodeIterations?: number;
     /** Maximum reroll iterations allowed per die (default: 1,000) */
     maxRerollIterations?: number;
+    /** Variable context for `@name` / `@{name}` references (default: empty) */
+    context?: Record<string, number>;
+    /** Behavior when a referenced variable is missing from context (default: 'throw') */
+    onMissingVariable?: 'throw' | 'zero';
 };
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/F;;;;GAIG;AACH,oBAAY,eAAe;IACzB,eAAe,IAAI;IACnB,OAAO,IAAI;IACX,OAAO,IAAI;IACX,eAAe,IAAI;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,28 +1,29 @@
 {
   "name": "roll-parser",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-beta.0",
   "description": "High-performance dice notation parser for tabletop RPGs. TypeScript-first, Bun-optimized.",
   "type": "module",
   "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "bin": { "roll-parser": "./dist/cli.js" },
+  "bin": {
+    "roll-parser": "./dist/cli.js"
+  },
   "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./testing": {
       "types": "./dist/testing.d.ts",
-      "import": "./dist/testing.mjs",
-      "require": "./dist/testing.js"
-    }
+      "default": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "src",
+    "CHANGELOG.md",
     "!src/**/*.test.ts"
   ],
   "keywords": [
@@ -60,26 +61,29 @@
     "check:version": "bun scripts/check-version.ts",
     "check:changelog": "bun scripts/check-changelog.ts",
     "clean": "rm -rf dist coverage",
-    "build": "bun run clean && bun run build:esm && bun run build:cjs && bun run build:esm:testing && bun run build:cjs:testing && bun run build:cli && bun run build:types",
-    "build:esm": "bun build src/index.ts --outfile dist/index.mjs --target bun",
-    "build:cjs": "bun build src/index.ts --outfile dist/index.js --target node",
-    "build:esm:testing": "bun build src/testing.ts --outfile dist/testing.mjs --target bun",
-    "build:cjs:testing": "bun build src/testing.ts --outfile dist/testing.js --target node",
-    "build:cli": "bun build src/cli/index.ts --outfile dist/cli.js --target node",
+    "build": "bun run clean && bun run build:lib && bun run build:testing && bun run build:cli && bun run build:types",
+    "build:lib": "bun build src/index.ts --outdir dist --target node --sourcemap=linked",
+    "build:testing": "bun build src/testing.ts --outdir dist --target node --sourcemap=linked",
+    "build:cli": "bun build src/cli/index.ts --outdir dist --entry-naming 'cli.[ext]' --target node --sourcemap=linked",
     "build:types": "tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "check:package": "attw --pack . --profile esm-only && publint",
+    "bench": "bun run bench/roll.bench.ts",
     "test": "bun test",
-    "test:node": "node -e \"import('./dist/index.mjs').then(m => { const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('ESM smoke failed: total=' + r.total); console.log('Node.js ESM smoke: ok'); })\" && node -e \"const m = require('./dist/index.js'); const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('CJS smoke failed: total=' + r.total); console.log('Node.js CJS smoke: ok');\"",
+    "test:node": "node -e \"import('./dist/index.js').then(m => { const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('ESM smoke failed: total=' + r.total); console.log('Node.js ESM smoke: ok'); })\" && node -e \"const m = require('./dist/index.js'); const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('require(esm) smoke failed: total=' + r.total); console.log('Node.js require(esm) smoke: ok');\"",
     "test:watch": "bun test --watch",
-    "test:ci": "bun test --bail",
-    "validate": "bun run check && bun run build && bun test:ci",
+    "test:ci": "bun test --bail --coverage",
+    "validate": "bun run check && bun run build && bun run check:package && bun test:ci",
     "coverage": "bun test --coverage",
-    "release:dry": "bun run check:version && bun run check:changelog && bun run check && bun run build && bun test",
+    "release:dry": "bun run check:version && bun run check:changelog && bun run check && bun run build && bun run check:package && bun test",
     "prepublishOnly": "bun run release:dry"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.4",
     "@biomejs/biome": "^2.4.9",
     "@types/bun": "^1.3.0",
     "fast-check": "^4.6.0",
+    "mitata": "^1.0.34",
+    "publint": "^0.3.21",
     "typescript": "^6.0.2"
   },
   "engines": {

package/src/cli/args.ts

@@ -59,7 +59,8 @@ export function parseArgs(argv: string[]): ParseArgsResult {
       seed = value;
     } else if (arg.startsWith('--')) {
       return { ok: false, error: `Unknown option: ${arg}` };
-    } else if (arg.startsWith('-') && arg.length > 1 && !/^\d/.test(arg.slice(1))) {
+    } else if (arg.startsWith('-') && arg.length > 1 && !/^[\ddD(]/.test(arg.slice(1))) {
+      // Negative prefix notation (-3, -d6, -D6, -dF, -(2d6)) stays positional
       return { ok: false, error: `Unknown option: ${arg}` };
     } else {
       positional.push(arg);

package/src/cli/format.ts

@@ -6,7 +6,7 @@
  * @module cli/format
  */
 
-import type { RollResult } from '../types';
+import type { RollResult } from '../types.js';
 
 /**
  * Formats a roll result for terminal display.
@@ -30,16 +30,20 @@ export function formatResult(result: RollResult, verbose: boolean): string {
  * Converts markdown-style dice markers to terminal-friendly forms.
  *
  * The evaluator uses markdown syntax in the rendered field:
- *   `~~value~~` — dropped dice
+ *   `~~value~~` — dropped dice or dropped group sub-rolls
  *   `**value**` — dice counted as success
  *   `__value__` — dice counted as failure
  *
  * For plain terminals these become `(value)`, `[value]`, and `{value}` so
  * the per-die classification stays visible without any markup dependency.
+ * Dropped spans can wrap a whole sub-roll (e.g. `~~1d8[2]~~` from
+ * `{1d8, 1d10}kh1`), so the strikethrough pattern accepts any tilde-free
+ * content, not just a single number. The evaluator never nests `~~`
+ * (see `stripInnerMarkers`), so the tilde-free span match is safe.
  */
 function formatRendered(rendered: string): string {
   return rendered
-    .replace(/~~(-?\d+)~~/g, '($1)')
     .replace(/\*\*(-?\d+)\*\*/g, '[$1]')
-    .replace(/__(-?\d+)__/g, '{$1}');
+    .replace(/__(-?\d+)__/g, '{$1}')
+    .replace(/~~([^~]+)~~/g, '($1)');
 }

package/src/cli/index.ts

@@ -6,11 +6,11 @@
  * @module cli/index
  */
 
-import { isRollParserError } from '../errors';
-import { VERSION } from '../index';
-import { roll } from '../roll';
-import { parseArgs } from './args';
-import { formatResult } from './format';
+import { isRollParserError } from '../errors.js';
+import { VERSION } from '../index.js';
+import { roll } from '../roll.js';
+import { parseArgs } from './args.js';
+import { formatResult } from './format.js';
 
 const HELP_TEXT = `roll-parser v${VERSION}
 
@@ -28,6 +28,22 @@ Examples:
   roll-parser 4d6dl1 --seed "character-str"
 `;
 
+/**
+ * Prints the notation with a caret under the error position for errors that
+ * carry one (LexerError/ParseError `position`, EvaluatorError `start`).
+ * Skipped for multi-line notations and out-of-range positions to keep the
+ * caret honest.
+ */
+function writeErrorContext(notation: string, error: Error): void {
+  const position =
+    'position' in error ? error.position : 'start' in error ? error.start : undefined;
+  if (typeof position !== 'number' || !Number.isInteger(position)) return;
+  if (notation.includes('\n') || position < 0 || position > notation.length) return;
+
+  process.stderr.write(`  ${notation}\n`);
+  process.stderr.write(`  ${' '.repeat(position)}^\n`);
+}
+
 function main(): void {
   const parsed = parseArgs(process.argv.slice(2));
 
@@ -65,6 +81,7 @@ function main(): void {
   } catch (error) {
     if (isRollParserError(error)) {
       process.stderr.write(`Error: ${error.message}\n`);
+      writeErrorContext(args.notation, error);
       process.exitCode = 1;
       return;
     }

package/src/errors.ts

@@ -11,12 +11,15 @@
  *
  * Lexer: `UNEXPECTED_CHARACTER`, `UNEXPECTED_IDENTIFIER`
  * Parser: `UNEXPECTED_TOKEN`, `UNEXPECTED_END`, `EXPECTED_TOKEN`,
- *   `INVALID_EXPLODE_TARGET`, `INVALID_SUCCESS_COUNT_TARGET`, `NESTED_VERSUS`,
- *   `INVALID_FUNCTION_ARITY`
+ *   `INVALID_MODIFIER_TARGET`, `INVALID_EXPLODE_TARGET`, `INVALID_REROLL_TARGET`,
+ *   `INVALID_SUCCESS_COUNT_TARGET`, `INVALID_SORT_TARGET`,
+ *   `INVALID_CRIT_THRESHOLD_TARGET`, `NESTED_VERSUS`, `INVALID_FUNCTION_ARITY`,
+ *   `AMBIGUOUS_DICE_CHAIN`, `MAX_DEPTH_EXCEEDED`
  * Evaluator: `INVALID_DICE_COUNT`, `INVALID_DICE_SIDES`, `DICE_LIMIT_EXCEEDED`,
  *   `DIVISION_BY_ZERO`, `MODULO_BY_ZERO`, `UNKNOWN_OPERATOR`, `UNKNOWN_NODE_TYPE`,
  *   `INVALID_MODIFIER_COUNT`, `EXPLODE_LIMIT_EXCEEDED`, `REROLL_LIMIT_EXCEEDED`,
- *   `INVALID_THRESHOLD`, `NESTED_VERSUS`, `UNKNOWN_FUNCTION`
+ *   `INVALID_THRESHOLD`, `NESTED_VERSUS`, `UNKNOWN_FUNCTION`, `UNDEFINED_VARIABLE`,
+ *   `INVALID_VARIABLE_VALUE`, `NON_FINITE_RESULT`
  */
 const ROLL_PARSER_ERROR_CODES = [
   'UNEXPECTED_CHARACTER',
@@ -32,14 +35,23 @@ const ROLL_PARSER_ERROR_CODES = [
   'UNKNOWN_OPERATOR',
   'UNKNOWN_NODE_TYPE',
   'INVALID_MODIFIER_COUNT',
+  'INVALID_MODIFIER_TARGET',
   'EXPLODE_LIMIT_EXCEEDED',
   'INVALID_EXPLODE_TARGET',
   'REROLL_LIMIT_EXCEEDED',
+  'INVALID_REROLL_TARGET',
   'INVALID_SUCCESS_COUNT_TARGET',
+  'INVALID_SORT_TARGET',
+  'INVALID_CRIT_THRESHOLD_TARGET',
   'INVALID_THRESHOLD',
   'NESTED_VERSUS',
   'INVALID_FUNCTION_ARITY',
   'UNKNOWN_FUNCTION',
+  'UNDEFINED_VARIABLE',
+  'INVALID_VARIABLE_VALUE',
+  'AMBIGUOUS_DICE_CHAIN',
+  'MAX_DEPTH_EXCEEDED',
+  'NON_FINITE_RESULT',
 ] as const;
 
 export type RollParserErrorCode = (typeof ROLL_PARSER_ERROR_CODES)[number];