roll-parser 3.1.0 → 3.2.0

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

@@ -10,17 +10,18 @@
  * excluded from counting and are never tagged.
  *
  * Mutates the input pool in place to add `'success'` / `'failure'` modifier
- * flags — mirrors the mutation pattern of explode and reroll modifiers. Each
- * tag is written at most once per die: a group counted after its members
- * (`{4d6>=5}>=1`) runs this pass twice over the same dice, and the parse-time
- * reject that blocks a direct `4d6>=5>=4` does not reach through a group.
+ * flags — mirrors the mutation pattern of explode and reroll modifiers. The
+ * tags are rebuilt, not appended: a group counted after its members
+ * (`{4d6>=5}<=2f5`) runs this pass twice over the same dice, and the outermost
+ * pass is the one whose arithmetic `RollResult.successes` / `failures` and the
+ * rendered markers report.
  *
  * @module evaluator/modifiers/success-count
  */
 
 import type { DieResult, ResolvedComparePoint } from '../../types.js';
 import { matchesCondition } from './compare.js';
-import { isVersusDc } from './flags.js';
+import { isVersusDc, stripFlags, TALLY_FLAGS } from './flags.js';
 
 export type SuccessCountResult = {
   total: number;
@@ -33,27 +34,33 @@ export function countSuccesses(
   threshold: ResolvedComparePoint,
   failThreshold: ResolvedComparePoint | undefined,
   hasVersusDc: boolean,
+  poolAlreadyCounted: boolean,
 ): SuccessCountResult {
   let successes = 0;
   let failures = 0;
 
   // ! Excluded up front, never inside the loop below. Even short-circuited on a
   // ! false flag, a `hasVersusDc && isVersusDc(die)` guard in this loop costs
-  // ! ~9% on `10d10>=6f1` — measured, not assumed (#281). Filtering keeps the
+  // ! ~9% on `10d10>=6f1` — measured, not assumed. Filtering keeps the
   // ! hot body identical to the pre-exclusion one and pays an allocation only
   // ! on the `vs` path. The dice are the same objects either way, so the
   // ! `'success'` / `'failure'` tags written below still land on the pool.
   const pool = hasVersusDc ? dice.filter((die) => !isVersusDc(die)) : dice;
 
-  // ! The guards below only stop the *same* tag being written twice. A nested
-  // ! count with a different threshold still appends to the first pass's tags,
-  // ! so a die can end up both `'success'` and `'failure'`, and the returned
-  // ! counts then disagree with the tags in `rolls`.
+  // ! Dropped dice are stripped too, not just the ones re-tagged below. This
+  // ! pass skips them, so an inner count's tag would otherwise survive into the
+  // ! top-level successes/failures scan and break `total === successes - failures`.
+  if (poolAlreadyCounted) {
+    for (const die of pool) {
+      die.modifiers = stripFlags(die.modifiers, TALLY_FLAGS);
+    }
+  }
+
   for (const die of pool) {
     if (die.modifiers.includes('dropped')) continue;
 
     if (matchesCondition(die.result, threshold.operator, threshold.value)) {
-      if (!die.modifiers.includes('success')) die.modifiers.push('success');
+      die.modifiers.push('success');
       successes += 1;
       continue;
     }
@@ -62,7 +69,7 @@ export function countSuccesses(
       failThreshold != null &&
       matchesCondition(die.result, failThreshold.operator, failThreshold.value)
     ) {
-      if (!die.modifiers.includes('failure')) die.modifiers.push('failure');
+      die.modifiers.push('failure');
       failures += 1;
     }
   }

package/src/notation.ts

@@ -0,0 +1,24 @@
+/**
+ * Notation serialization shared by the two breakdown builders — the
+ * evaluator's `expression`/`rendered` strings and `render.ts`.
+ *
+ * @module notation
+ */
+
+// ! `cs`, `cf`, `s`, and `sd` are the only codes ending in a letter the lexer
+// ! scans as an identifier — maximal munch then swallows what follows, so
+// ! `cs` + `cf` re-lexes as `cscf`. `4dF` and `!p` are their own tokens.
+const BARE_MODIFIER_END = /(?:cs|cf|sd|s)$/;
+
+const STARTS_WITH_LETTER = /^[A-Za-z]/;
+
+/**
+ * Appends a modifier code to the expression built so far, separating the two
+ * with a space when concatenating them would re-lex as a single identifier.
+ * The space is the same separator the input used to make them parse.
+ */
+export function joinModifierCode(expression: string, code: string): string {
+  return BARE_MODIFIER_END.test(expression) && STARTS_WITH_LETTER.test(code)
+    ? `${expression} ${code}`
+    : `${expression}${code}`;
+}

package/src/parser/guards.ts

@@ -61,7 +61,7 @@ export function unwrapAllTransparent(node: ASTNode): ASTNode {
  * Returns `true` when `node` or any descendant satisfies `isHit`. Recurses
  * directly through the entire node vocabulary: arithmetic operands,
  * modifier-chain targets, `Versus` sides, function arguments, and group
- * sub-expressions. This is the shared driver behind the four deep walkers
+ * sub-expressions. This is the shared driver behind the deep walkers
  * below. The shallow walkers (`containsDicePool`, `containsFatePool`) stay
  * hand-written because their rejection semantics deliberately stop at
  * arithmetic boundaries.
@@ -112,6 +112,9 @@ const isDicePoolHit = (current: ASTNode): boolean =>
 
 const isFateDiceHit = (current: ASTNode): boolean => current.type === 'FateDice';
 
+const isDiceHit = (current: ASTNode): boolean =>
+  current.type === 'Dice' || current.type === 'FateDice';
+
 const isMultiSubGroupHit = (current: ASTNode): boolean =>
   current.type === 'Group' && current.expressions.length >= 2;
 
@@ -168,6 +171,94 @@ export function deepContainsDicePool(node: ASTNode): boolean {
   return someDescendant(node, isDicePoolHit);
 }
 
+/**
+ * Returns `true` when this node's total provably equals the sum of its kept
+ * dice faces: a pool, a chain of pool modifiers over one, or an addition of
+ * those. A multi-sub-roll `Group` qualifies when every sub-roll does, since its
+ * total is their sum and `evalGroupKeepDrop` re-flags dropped sub-rolls' dice.
+ *
+ * Guards the single-sub-roll `Group` keep/drop target, whose flat-pool path
+ * totals `sumKeptDice`. Anything else in there — a literal, a subtracted or
+ * scaled dice term, a function call, a success count — contributes to the
+ * group's own total but not to that face sum, so `{2d6+3}kh2` would lose the
+ * `+3` and `{2d6-1d4}kh3` would flip the `1d4` from `-3` to `+3` while dropping
+ * nothing.
+ */
+export function sumsToKeptFaces(node: ASTNode): boolean {
+  switch (node.type) {
+    case 'Dice':
+    case 'FateDice':
+      return true;
+    case 'KeepDrop':
+    case 'Explode':
+    case 'Reroll':
+    case 'DieBound':
+    case 'Sort':
+    case 'CritThreshold':
+      return sumsToKeptFaces(node.target);
+    case 'Grouped':
+      return sumsToKeptFaces(node.expression);
+    case 'Group':
+      return node.expressions.every(sumsToKeptFaces);
+    case 'BinaryOp':
+      return node.operator === '+' && sumsToKeptFaces(node.left) && sumsToKeptFaces(node.right);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Returns `true` when comparing this node's dice one face at a time is faithful
+ * to what it totals. Shaped like `sumsToKeptFaces` but answering a different
+ * question, so the two differ on three node types:
+ *
+ * - `SuccessCount` passes — a nested count re-scores the very same faces.
+ * - `Versus` looks only at its roll side — no pool pass ever counts a DC.
+ * - a multi-sub-roll `Group` fails everywhere, because its units are subtotals.
+ *   `sumsToKeptFaces` accepts one, a sum of subtotals still being a face sum.
+ *
+ * Guards the flat success-count path, whose units are individual dice. The
+ * subtotal path takes a direct multi-sub-roll `Group` before this is consulted.
+ */
+export function countsPerDie(node: ASTNode): boolean {
+  switch (node.type) {
+    case 'Dice':
+    case 'FateDice':
+      return true;
+    case 'KeepDrop':
+    case 'Explode':
+    case 'Reroll':
+    case 'DieBound':
+    case 'Sort':
+    case 'CritThreshold':
+    case 'SuccessCount':
+      return countsPerDie(node.target);
+    case 'Versus':
+      return countsPerDie(node.roll);
+    case 'Grouped':
+      return countsPerDie(node.expression);
+    case 'Group':
+      return node.expressions.length === 1 && node.expressions.every(countsPerDie);
+    case 'BinaryOp':
+      return node.operator === '+' && countsPerDie(node.left) && countsPerDie(node.right);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Deep-walks a node to find any descendant `Dice` or `FateDice`. Unlike
+ * `deepContainsDicePool`, a multi-sub-roll `Group` is not a hit in its own
+ * right — only real dice are.
+ *
+ * Used by the success-count parser guard, which tallies individual dice rather
+ * than subtotals: a literal-only group satisfies `containsDicePool` yet rolls
+ * nothing to tally.
+ */
+export function containsDice(node: ASTNode): boolean {
+  return someDescendant(node, isDiceHit);
+}
+
 /**
  * Returns `true` if the pool this node resolves to is (or wraps) a `FateDice`
  * pool. Walks through chained pool modifiers (`KeepDrop` / `Explode` /

package/src/parser/parser.ts

@@ -32,11 +32,14 @@ import type {
 } from './ast.js';
 import { isCritThreshold, isSuccessCount } from './ast.js';
 import {
+  containsDice,
   containsDicePool,
   containsFatePool,
   containsMultiSubGroup,
   containsVersus,
+  countsPerDie,
   deepContainsDicePool,
+  sumsToKeptFaces,
   unwrapAllTransparent,
   unwrapGrouped,
 } from './guards.js';
@@ -767,6 +770,39 @@ export class Parser {
       );
     }
 
+    // ! A single-sub-roll Group is the flat-pool escape hatch, so `containsDicePool`
+    // ! deep-walks the arithmetic that `(1d6+5)kh1` rejects outright — but the flat
+    // ! path totals `sumKeptDice`, faces only. `{2d6+3}kh2` and `{2d6-1d4}kh3` are
+    // ! exactly the drop that reject exists to prevent.
+    const base = unwrapAllTransparent(target);
+    if (base.type === 'Group' && base.expressions.length === 1) {
+      const inner = base.expressions[0];
+      if (inner != null) {
+        // Single-sub Groups hide a count from the shallow reject at the top of this
+        // method, so peel them to any depth and `{4d6>=5}kh1`, `{{4d6>=5}}kh1`, and
+        // `(4d6>=5)kh1` all report one code. Peeling only picks which error the
+        // caller sees — `sumsToKeptFaces` below refuses a count either way.
+        let innermost = inner;
+        while (true) {
+          const peeled = unwrapGrouped(innermost);
+          if (peeled.type !== 'Group' || peeled.expressions.length !== 1) break;
+          const next = peeled.expressions[0];
+          if (next == null) break;
+          innermost = next;
+        }
+        this.rejectSuccessCountTarget(innermost, token);
+
+        if (!sumsToKeptFaces(inner)) {
+          throw new ParseError(
+            `Keep/drop on a single-sub-roll group requires added dice terms only`,
+            'INVALID_KEEP_DROP_TARGET',
+            token.position,
+            token,
+          );
+        }
+      }
+    }
+
     const kind =
       token.type === TokenType.KEEP_HIGH || token.type === TokenType.KEEP_LOW ? 'keep' : 'drop';
 
@@ -1087,7 +1123,12 @@ export class Parser {
     // Success counting reads a raw pool, so arithmetic or composition wrappers
     // (`1>=3`, `(1+2)>=3`, `(1d6*2)>=10`, `(1d20 vs 15)>=1`) would be silently
     // ignored.
-    if (!containsDicePool(target)) {
+    //
+    // ! Both checks are load-bearing. `containsDicePool` rejects those wrappers
+    // ! despite the dice; `containsDice` rejects a group holding none
+    // ! (`{3, 5, 7}>=4`), which the multi-sub-roll rule accepts — that rule is
+    // ! written for keep/drop, whose units are subtotals, not dice.
+    if (!containsDicePool(target) || !containsDice(target)) {
       throw new ParseError(
         `Success counting requires a dice pool target`,
         'INVALID_SUCCESS_COUNT_TARGET',
@@ -1096,6 +1137,20 @@ export class Parser {
       );
     }
 
+    // ! A multi-sub-roll group is counted by subtotal, and only `evalSuccessCount`
+    // ! knows how — it needs the group as its direct target. Reached any other way
+    // ! (`{{2d6, 2d8}}>=4`, `({2d6, 2d8})>=4`, `{2d6, 2d8}kh1>=4`) the subtotals are
+    // ! gone by the time the count runs, leaving loose faces to compare.
+    const isSubtotalGroup = target.type === 'Group' && target.expressions.length >= 2;
+    if (!isSubtotalGroup && !countsPerDie(target)) {
+      throw new ParseError(
+        `Success counting requires a target whose dice can be counted one face at a time`,
+        'INVALID_SUCCESS_COUNT_TARGET',
+        token.position,
+        token,
+      );
+    }
+
     const operator = this.getCompareOp(token);
     // Threshold binds at `BP.DICE_LEFT` — see `parseComparePoint` TSDoc.
     const value = this.parseExpression(BP.DICE_LEFT);

package/src/render.ts

@@ -9,6 +9,7 @@
  * @module render
  */
 
+import { joinModifierCode } from './notation.js';
 import type {
   DieResult,
   KeepDropSpec,
@@ -122,7 +123,6 @@ function failCode(point: ResolvedComparePoint): string {
 function expr(part: RollPart): string {
   switch (part.type) {
     case 'literal':
-      return String(part.value);
     case 'variable':
       return String(part.value);
     case 'dice':
@@ -140,17 +140,17 @@ function expr(part: RollPart): string {
     case 'functionCall':
       return `${part.name}(${part.args.map(expr).join(', ')})`;
     case 'keepDrop':
-      return `${expr(part.target)}${part.specs.map(keepDropCode).join('')}`;
+      return joinModifierCode(expr(part.target), part.specs.map(keepDropCode).join(''));
     case 'explode':
       return `${expr(part.target)}${explodeCode(part)}`;
     case 'reroll':
-      return `${expr(part.target)}${part.once ? 'ro' : 'r'}${comparePointCode(part.condition)}`;
+      return joinModifierCode(expr(part.target), rerollCode(part));
     case 'dieBound':
-      return `${expr(part.target)}${dieBoundCode(part)}`;
+      return joinModifierCode(expr(part.target), dieBoundCode(part));
     case 'sort':
-      return `${expr(part.target)}${part.order === 'ascending' ? 's' : 'sd'}`;
+      return joinModifierCode(expr(part.target), part.order === 'ascending' ? 's' : 'sd');
     case 'critThreshold':
-      return `${expr(part.target)}${critThresholdCode(part)}`;
+      return joinModifierCode(expr(part.target), critThresholdCode(part));
     case 'successCount':
       return `${expr(part.target)}${successCountCode(part)}`;
     case 'versus':
@@ -163,6 +163,10 @@ function explodeCode(part: Extract<RollPart, { type: 'explode' }>): string {
   return part.threshold == null ? marker : `${marker}${comparePointCode(part.threshold)}`;
 }
 
+function rerollCode(part: Extract<RollPart, { type: 'reroll' }>): string {
+  return `${part.once ? 'ro' : 'r'}${comparePointCode(part.condition)}`;
+}
+
 /** Negative bounds are parenthesized so the expression re-parses. */
 function dieBoundCode(part: Extract<RollPart, { type: 'dieBound' }>): string {
   return part.value < 0 ? `${part.bound}(${part.value})` : `${part.bound}${part.value}`;
@@ -172,7 +176,7 @@ function critThresholdCode(part: Extract<RollPart, { type: 'critThreshold' }>):
   return [
     ...part.successThresholds.map((threshold) => critCode('cs', threshold)),
     ...part.failThresholds.map((threshold) => critCode('cf', threshold)),
-  ].join('');
+  ].reduce(joinModifierCode, '');
 }
 
 function successCountCode(part: Extract<RollPart, { type: 'successCount' }>): string {
@@ -235,9 +239,8 @@ function poolOf(part: RollPart): DieResult[] {
 }
 
 /**
- * Marks one die. `plain` suppresses the three state marks for dice inside a
- * dropped sub-roll, where the group wrapper already carries the verdict —
- * crit and fumble survive, since they describe the face, not the selection.
+ * Marks one die. `plain` suppresses the three state marks inside a dropped
+ * sub-roll — the rule {@link DieMarks.droppedGroup} documents.
  */
 function markDie(die: DieResult, marks: DieMarks, plain: boolean): string {
   let text = String(die.result);
@@ -279,7 +282,7 @@ function renderModifier(
   plain: boolean,
 ): string {
   const pool = dice.length === 0 ? '' : renderPool(dice, marks, plain);
-  return `${expr(target)}${code}${pool}`;
+  return `${joinModifierCode(expr(target), code)}${pool}`;
 }
 
 function renderPart(part: RollPart, marks: DieMarks, plain: boolean): string {
@@ -316,21 +319,20 @@ function renderPart(part: RollPart, marks: DieMarks, plain: boolean): string {
     case 'explode':
       return renderModifier(part.target, explodeCode(part), part.rolls, marks, plain);
     case 'reroll':
-      return renderModifier(
-        part.target,
-        `${part.once ? 'ro' : 'r'}${comparePointCode(part.condition)}`,
-        part.rolls,
-        marks,
-        plain,
-      );
+      return renderModifier(part.target, rerollCode(part), part.rolls, marks, plain);
     case 'successCount':
-      return renderModifier(part.target, successCountCode(part), part.rolls, marks, plain);
+      // Subtotal counting renders through the group, which shows each sub-roll's
+      // own dice; only the flat form collapses into one bracket.
+      return part.target.type === 'group' && part.target.parts.length >= 2
+        ? `${renderPart(part.target, marks, plain)}${successCountCode(part)}`
+        : renderModifier(part.target, successCountCode(part), part.rolls, marks, plain);
+    // These three render as their own normalized expression plus a pool.
     case 'dieBound':
-      return `${expr(part.target)}${dieBoundCode(part)}${renderPool(poolOf(part.target), marks, plain)}`;
+      return `${expr(part)}${renderPool(poolOf(part.target), marks, plain)}`;
     case 'sort':
-      return `${expr(part.target)}${part.order === 'ascending' ? 's' : 'sd'}${renderPool(part.rolls, marks, plain)}`;
+      return `${expr(part)}${renderPool(part.rolls, marks, plain)}`;
     case 'critThreshold':
-      return `${expr(part.target)}${critThresholdCode(part)}${renderPool(poolOf(part.target), marks, plain)}`;
+      return `${expr(part)}${renderPool(poolOf(part.target), marks, plain)}`;
   }
 }
 

package/src/types.ts

@@ -165,8 +165,9 @@ export type DieResult = {
   /** 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.
+   * Raw first roll before any mutation — compound-explode accumulation, the
+   * `!p` decrement, or a `minN`/`maxN` clamp. 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`.
    */
@@ -234,7 +235,10 @@ export type RollPartBase = {
  * - `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.
+ *   accumulation, reroll flags, keep/drop flags, success/failure tags). No deep
+ *   clone. A part's own numbers record what that part computed, so an inner
+ *   `successCount` re-scored by an outer one (`{4d6>=5}<=2f5`) keeps its
+ *   tally while the dice it shares show the outer count's tags.
  *
  * Meta-expression sub-trees (`4d6kh(1d2)`, `(1+1)d6` counts/sides, computed
  * thresholds) are not surfaced as nested parts — their resolved numbers
@@ -449,6 +453,14 @@ export type RollResult = Readonly<{
    * arithmetic on top of a success count (e.g. `{5d6>=5}+2`) affects `total`
    * but not `successes`. Success counts are terminal, so the group braces are
    * required: `5d6>=5 * 2` is an `INVALID_SUCCESS_COUNT_TARGET` parse error.
+   *
+   * Braces also let a second count re-count the same pool (`{4d6>=5}<=2f5`).
+   * The outermost count owns the outcome: it re-scores the pool against its own
+   * thresholds, so no die is ever both a success and a failure, and dice it
+   * does not count come out untagged rather than keeping the inner count's
+   * tags. The DC side of a `vs` is never tallied here; it keeps whatever tags
+   * an inner count gave it, unless the outer count scores subtotals rather
+   * than dice, which leaves every die untagged.
    */
   successes?: number;
   /**

package/src/version.ts

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