roll-parser 3.0.0-alpha.0 → 3.0.0

package/src/evaluator/modifiers/reroll.ts

@@ -9,49 +9,37 @@
  * @module evaluator/modifiers/reroll
  */
 
-import type { RNG } from '../../rng/types';
-import type { CompareOp, DieResult } from '../../types';
-import { EvaluatorError, type EvalEnv } from '../evaluator';
-import { matchesCondition } from './compare';
+import { EvaluatorError } from '../../errors.js';
+import type { RNG } from '../../rng/types.js';
+import type { CompareOp, DieResult } from '../../types.js';
+import { createDieResult, createFateDieResult } from '../die.js';
+import { chargeDie, type EvalEnv } from '../env.js';
+import { matchesCondition } from './compare.js';
+import { isVersusDc, REROLL_SLOT_FLAGS, rewriteFlags } from './flags.js';
 
-/** Default maximum reroll iterations per die. */
+/**
+ * Default value of `EvaluationOptions.maxRerollIterations`: how many times a
+ * single die may be re-rolled by `r` before `REROLL_LIMIT_EXCEEDED` is
+ * thrown.
+ *
+ * Per die, not per pool — it bounds notations like `1d1r<2`, whose reroll
+ * condition can never stop matching. `ro` re-rolls exactly once and is
+ * unaffected.
+ *
+ * @category Limits
+ */
 export const DEFAULT_MAX_REROLL_ITERATIONS = 1_000;
 
-export { matchesCondition };
-
 /**
  * Rolls a replacement die for the given sides, charging it against the global
  * dice limit. Fate dice (sides === 0) re-roll on the {-1, 0, +1} range.
  */
 function rollReplacement(sides: number, rng: RNG, env: EvalEnv): DieResult {
-  if (env.totalDiceRolled + 1 > env.maxDice) {
-    throw new EvaluatorError(
-      `Total dice count ${env.totalDiceRolled + 1} exceeds limit of ${env.maxDice}`,
-      'DICE_LIMIT_EXCEEDED',
-      'Reroll',
-    );
-  }
-  env.totalDiceRolled += 1;
-
-  if (sides === 0) {
-    const result = rng.nextInt(-1, 1);
-    return {
-      sides: 0,
-      result,
-      modifiers: [],
-      critical: false,
-      fumble: false,
-    };
-  }
+  chargeDie(env, 'Reroll');
 
-  const result = rng.nextInt(1, sides);
-  return {
-    sides,
-    result,
-    modifiers: [],
-    critical: result === sides && sides > 1,
-    fumble: result === 1,
-  };
+  if (sides === 0) return createFateDieResult(rng.nextInt(-1, 1), []);
+
+  return createDieResult(sides, rng.nextInt(1, sides), []);
 }
 
 function rerollLimitError(maxIterations: number): EvaluatorError {
@@ -67,16 +55,7 @@ function rerollLimitError(maxIterations: number): EvaluatorError {
  * keep/drop modifier) are left alone.
  */
 function canReroll(die: DieResult): boolean {
-  return !die.modifiers.includes('dropped');
-}
-
-/**
- * Returns the die's modifiers with any "slot" flags removed. Slot flags
- * (`kept`, `dropped`, `rerolled`) are controlled by the surrounding logic
- * and should be reassigned each pass.
- */
-function stripSlotFlags(modifiers: DieResult['modifiers']): DieResult['modifiers'] {
-  return modifiers.filter((m) => m !== 'kept' && m !== 'dropped' && m !== 'rerolled');
+  return !die.modifiers.includes('dropped') && !isVersusDc(die);
 }
 
 /**
@@ -105,24 +84,22 @@ export function applyRecursiveReroll(
     let current = original;
     let iterations = 0;
 
+    // Mutate flags in place — the same DieResult objects are shared with
+    // the RollPart tree, and both views must reflect reroll state.
     while (matchesCondition(current.result, operator, value)) {
       if (iterations >= env.maxRerollIterations) {
         throw rerollLimitError(env.maxRerollIterations);
       }
 
-      result.push({
-        ...current,
-        modifiers: [...stripSlotFlags(current.modifiers), 'rerolled', 'dropped'],
-      });
+      current.modifiers = rewriteFlags(current.modifiers, REROLL_SLOT_FLAGS, 'rerolled', 'dropped');
+      result.push(current);
 
       current = rollReplacement(current.sides, rng, env);
       iterations += 1;
     }
 
-    result.push({
-      ...current,
-      modifiers: [...stripSlotFlags(current.modifiers), 'kept'],
-    });
+    current.modifiers = rewriteFlags(current.modifiers, REROLL_SLOT_FLAGS, 'kept');
+    result.push(current);
   }
 
   return result;
@@ -148,24 +125,19 @@ export function applyRerollOnce(
       continue;
     }
 
+    // Mutate flags in place — see `applyRecursiveReroll`.
     if (!matchesCondition(original.result, operator, value)) {
-      result.push({
-        ...original,
-        modifiers: [...stripSlotFlags(original.modifiers), 'kept'],
-      });
+      original.modifiers = rewriteFlags(original.modifiers, REROLL_SLOT_FLAGS, 'kept');
+      result.push(original);
       continue;
     }
 
-    result.push({
-      ...original,
-      modifiers: [...stripSlotFlags(original.modifiers), 'rerolled', 'dropped'],
-    });
+    original.modifiers = rewriteFlags(original.modifiers, REROLL_SLOT_FLAGS, 'rerolled', 'dropped');
+    result.push(original);
 
     const replacement = rollReplacement(original.sides, rng, env);
-    result.push({
-      ...replacement,
-      modifiers: [...stripSlotFlags(replacement.modifiers), 'kept'],
-    });
+    replacement.modifiers = rewriteFlags(replacement.modifiers, REROLL_SLOT_FLAGS, 'kept');
+    result.push(replacement);
   }
 
   return result;

package/src/evaluator/modifiers/sort.ts

@@ -0,0 +1,43 @@
+/**
+ * Sort modifier implementation.
+ *
+ * Sort is purely cosmetic — it reorders the dice produced by its target in
+ * ascending or descending order of `result` without touching any flag
+ * (`kept`, `dropped`, `critical`, `fumble`, `rerolled`, `meta`) or the total.
+ * Dropped dice stay in the pool and sort alongside kept dice so readers can
+ * see where the dropped value landed in the ordered sequence.
+ *
+ * DC dice are the exception: they hold their positions rather than sorting,
+ * so a `vs` comparison's DC faces never appear shuffled into the roll-side
+ * pool they are not a member of.
+ *
+ * @module evaluator/modifiers/sort
+ */
+
+import type { DieResult } from '../../types.js';
+import { isVersusDc } from './flags.js';
+
+/**
+ * Returns a sorted copy of `dice` in the given order, preserving every die's
+ * original flags and metadata. Comparison is on `.result` — the raw face
+ * value is what the user sees in rendered output, so ordering by raw value
+ * matches the visual intent regardless of any `kept`/`dropped` flagging.
+ *
+ * Relies on `Array.prototype.sort` being stable — equal-valued dice retain
+ * their original insertion order.
+ */
+export function sortDice(dice: DieResult[], order: 'ascending' | 'descending'): DieResult[] {
+  const cmp =
+    order === 'ascending'
+      ? (a: DieResult, b: DieResult) => a.result - b.result
+      : (a: DieResult, b: DieResult) => b.result - a.result;
+
+  const sortable = dice.filter((die) => !isVersusDc(die));
+  if (sortable.length === dice.length) return [...dice].sort(cmp);
+
+  // Sort only the pool members, then lay them back into the slots they came
+  // from, leaving every DC die exactly where it was.
+  sortable.sort(cmp);
+  let next = 0;
+  return dice.map((die) => (isVersusDc(die) ? die : (sortable[next++] as DieResult)));
+}

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

@@ -15,13 +15,9 @@
  * @module evaluator/modifiers/success-count
  */
 
-import type { CompareOp, DieResult } from '../../types';
-import { matchesCondition } from './compare';
-
-export type ResolvedThreshold = {
-  operator: CompareOp;
-  value: number;
-};
+import type { DieResult, ResolvedComparePoint } from '../../types.js';
+import { matchesCondition } from './compare.js';
+import { isVersusDc } from './flags.js';
 
 export type SuccessCountResult = {
   total: number;
@@ -31,13 +27,14 @@ export type SuccessCountResult = {
 
 export function countSuccesses(
   dice: DieResult[],
-  threshold: ResolvedThreshold,
-  failThreshold?: ResolvedThreshold,
+  threshold: ResolvedComparePoint,
+  failThreshold?: ResolvedComparePoint,
 ): SuccessCountResult {
   let successes = 0;
   let failures = 0;
 
   for (const die of dice) {
+    if (isVersusDc(die)) continue;
     if (die.modifiers.includes('dropped')) continue;
 
     if (matchesCondition(die.result, threshold.operator, threshold.value)) {

package/src/index.ts

@@ -4,69 +4,108 @@
  * @module roll-parser
  */
 
-// * Error hierarchy
-export { RollParserError, isRollParserError } from './errors';
-export type { RollParserErrorCode } from './errors';
+import { version } from './version.js';
 
-// * Lexer exports
-export { LexerError } from './lexer/lexer';
-
-// * Parser exports
-export { parse, ParseError } from './parser/parser';
+export type { ErrorSpan, NotationErrorCode, RollParserErrorCode } from './errors.js';
+export {
+  getErrorSpan,
+  isNotationError,
+  isRollParserError,
+  NOTATION_ERROR_CODES,
+  ROLL_PARSER_ERROR_CODES,
+  RollParserError,
+} from './errors.js';
+export {
+  DEFAULT_MAX_DICE,
+  DEFAULT_MAX_EXPLODE_ITERATIONS,
+  DEFAULT_MAX_REROLL_ITERATIONS,
+  EvaluatorError,
+  evaluate,
+} from './evaluator/evaluator.js';
+export { LexerError, lex } from './lexer/lexer.js';
+export type { Token } from './lexer/tokens.js';
+export { TokenType } from './lexer/tokens.js';
 export type {
   ASTNode,
   BinaryOpNode,
+  CritThreshold,
+  CritThresholdNode,
   DiceNode,
+  DieBoundNode,
   ExplodeNode,
   FateDiceNode,
   FunctionCallNode,
+  GroupedNode,
+  GroupNode,
+  KeepDropNode,
   LiteralNode,
-  ModifierNode,
+  NodeSpan,
   RerollNode,
+  SortNode,
   SuccessCountNode,
   UnaryOpNode,
+  VariableNode,
   VersusNode,
-} from './parser/ast';
+} from './parser/ast.js';
 export {
   isBinaryOp,
+  isCritThreshold,
   isDice,
+  isDieBound,
   isExplode,
   isFateDice,
   isFunctionCall,
+  isGroup,
+  isGrouped,
+  isKeepDrop,
   isLiteral,
-  isModifier,
   isReroll,
+  isSort,
   isSuccessCount,
   isUnaryOp,
+  isVariable,
   isVersus,
-} from './parser/ast';
-
-// * RNG exports
-export type { RNG } from './rng/types';
-export { SeededRNG } from './rng/seeded';
-
-// * Evaluator exports
-export {
-  DEFAULT_MAX_DICE,
-  DEFAULT_MAX_EXPLODE_ITERATIONS,
-  DEFAULT_MAX_REROLL_ITERATIONS,
-  evaluate,
-  EvaluatorError,
-} from './evaluator/evaluator';
+} from './parser/ast.js';
+export { MAX_PARSE_DEPTH, ParseError, parse } from './parser/parser.js';
+export type { RngState } from './rng/seeded.js';
+export { SeededRNG } from './rng/seeded.js';
+export type { RNG } from './rng/types.js';
+export type { RollOptions } from './roll.js';
+export { roll } from './roll.js';
 export type {
   CompareOp,
   ComparePoint,
   DieModifier,
   DieResult,
   EvaluateOptions,
+  EvaluationOptions,
+  KeepDropSpec,
+  ResolvedComparePoint,
+  ResolvedCritThreshold,
+  RollPart,
+  RollPartBase,
+  RollPartType,
   RollResult,
-} from './types';
-export { DegreeOfSuccess } from './types';
-
-// * Public API
-export { roll } from './roll';
-export type { RollOptions } from './roll';
-
-import pkg from '../package.json';
+} from './types.js';
+export { DegreeOfSuccess } from './types.js';
 
-export const VERSION: string = pkg.version;
+/**
+ * Installed roll-parser version — the exact string in `package.json`, so
+ * pre-releases keep their suffix (`'3.0.0-beta.0'`). Sourced from the
+ * generated `src/version.ts`, kept in sync with the manifest by
+ * `bun run generate:version` and gated by `check:version` and CI.
+ *
+ * Useful in bug reports and for feature-gating against a minimum version. The
+ * CLI prints it for `--version` and in the `--help` header.
+ *
+ * @example
+ * ```typescript
+ * import { VERSION } from 'roll-parser';
+ *
+ * VERSION; // e.g. '3.0.0', or '3.1.0-beta.0' on a pre-release
+ * VERSION.startsWith('3.'); // true
+ * ```
+ *
+ * @category Core
+ */
+export const VERSION: string = version;