roll-parser 3.1.0 → 3.2.1

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.1] - 2026-08-10
+
+### Changed
+
+- The three errors for operands that must be whole numbers — dice count, dice sides, and keep/drop count — now name the fix instead of only the value: `5d(20/3)` reports `Invalid dice sides: 6.666666666666667 (use 'floor', 'ceil', or 'round')`. Division still does not floor, so a fraction there stays an error rather than being rounded for you; the hint points at the escape hatch the notation already has. `1d0`, negative counts, and non-finite values keep their bare messages, since no rounding rescues them, and the value is printed exact — a fixed-width display rounded `1.00001` to `1`, naming a side count the evaluator accepts ([#318](https://github.com/edloidas/roll-parser/issues/318))
+
+### Documentation
+
+- `README.md`'s "Division does not floor" gotcha now covers the dice-operand consequence, with `5d(20/3)` and its `5d(round(20/3))` rewrite ([#318](https://github.com/edloidas/roll-parser/issues/318))
+
+## [3.2.0] - 2026-08-09
+
+Every entry below is a correctness fix, but several change what a working
+expression returns and five group forms that used to evaluate now throw.
+[MIGRATION.md](MIGRATION.md#upgrading-from-310-to-320) walks each one with a
+rewrite. Seeds are untouched: the same seed and notation roll the same faces
+they did in 3.1.0.
+
+### Fixed
+
+- Success counting a multi-sub-roll group now scores one success per sub-roll subtotal, the way keep/drop on the same node always did, so `{2d6, 2d6}>=10` finds the 11 it was missing. The dice stop being the units: `rendered` shows each sub-roll's own bracket, `rolls[].modifiers` comes back untagged, and `fT` thresholds weigh subtotals too. Targets whose arithmetic no per-die comparison ever reaches — `{3d20+5}>=21`, `{2d6*2}>=4`, `{2d6, 2d8}kh1>=4` — throw `INVALID_SUCCESS_COUNT_TARGET` instead of comparing faces against a number the sub-roll's math never produced ([#303](https://github.com/edloidas/roll-parser/issues/303))
+- A second success count reaching the same pool through group braces (`{4d6>=5f1}<=2f6`) now re-scores it outright rather than appending to the inner pass's tags, so no die comes back both `'success'` and `'failure'` and `successes`/`failures` describe `total` again. The outermost count owns the tags; dropped dice come out untagged, while the DC side of a `vs` keeps tags from an inner count, since no pool pass may tally it. `total` never moved ([#297](https://github.com/edloidas/roll-parser/issues/297))
+- Success counting a group that can never roll a die (`{3, 5, 7}>=4`, `{3, 5, 7}kh1>=4`) now throws `INVALID_SUCCESS_COUNT_TARGET` instead of returning the group's sum with `successes: 0`, which read the documented `successCount.total === successes - failures` invariant as `15 === 0`. A pool that is empty only at run time (`{3, 0d6}>=4`) totals 0 rather than the literal sum ([#304](https://github.com/edloidas/roll-parser/issues/304))
+- Keep/drop on a single-sub-roll group whose total is not the sum of its kept faces now throws `INVALID_KEEP_DROP_TARGET` instead of silently discarding the rest of the arithmetic. `{2d6+3}kh2` lost the `+3`, and `{2d6-1d4}kh3` — which drops nothing — flipped the `1d4` from `-3` to `+3`; `{2d6*2}kh2` and `{abs(1d6-1d8)}kh1` are refused for the same reason `(2d6+3)kh2` already was. The check is structural, so identity terms (`{2d6+0}kh2`) go with them. Additive pools (`{4d6+2d8}kh3`) and multi-sub-roll groups, which select on subtotals, are untouched. A brace-wrapped success count now reports `INVALID_SUCCESS_COUNT_TARGET` at any nesting depth, matching what `(4d6>=5)kh1` always did ([#302](https://github.com/edloidas/roll-parser/issues/302))
+- Penetrating explosion now records the face it rolled in `initialResult` on every die it appends, so the `initialResult ?? result` idiom `DieResult` documents recovers the natural face instead of the stored `raw - 1` — a natural 20 was indistinguishable from a 19. Bare `cs`/`cf` consequently judges a `!p` continuation by that face, so `1d6cf>5!p` and `1d6!pcf>5` agree where the README documented them as disagreeing. Separately, a `vs` roll whose explosion dice are clamped by `minN`/`maxN` (`1d20!min5 vs 30`) stops misreading the continuation as a second primary d20, which had been suppressing the natural-20/1 step ([#300](https://github.com/edloidas/roll-parser/issues/300))
+- `cs`, `cf`, `s`, and `sd` adjacent to another modifier now keep a space in `expression` and `rendered`, so the normalized string re-parses. Those four codes end in a letter the lexer scans as an identifier, so maximal munch swallowed whatever followed: `1d20cs cf` normalized to `1d20cscf` and `4d6 s kh2` to `4d6s kh2`, neither of which round-trips through `parse`. `4dF` and `!p` end in letters but are their own tokens and stay flush ([#299](https://github.com/edloidas/roll-parser/issues/299))
+- Demo site: the equation chip keeps explode and reroll dice. It read only `sort` out of the part tree, so any other pool-bearing modifier's dice went missing from the chip ([#313](https://github.com/edloidas/roll-parser/issues/313))
+
+### Documentation
+
+- `MIGRATION.md` gains a 3.1.0 → 3.2.0 section covering all five newly rejected forms with a rewrite for each, plus the values that moved: `initialResult` on `!p` dice, one `vs` degree, the `expression`/`rendered` spacing, and the totals and tags of nested and grouped success counts ([#300](https://github.com/edloidas/roll-parser/issues/300), [#293](https://github.com/edloidas/roll-parser/issues/293))
+- README gains a `Reading crit and fumble` subsection showing the per-die loop over `result.rolls`, with `site/src/dice.ts` named as the working in-repo example. It documents the four traps such a loop hits — `'meta'` dice must be filtered, `'dc'` dice need a deliberate choice, `rendered` must never be spliced by bracket position, and the default crit rule fires on every pool's max face — and names `rendered`'s markdown as Discord-flavored, pointing at `renderBreakdown` for other dialects ([#293](https://github.com/edloidas/roll-parser/issues/293))
+- README's `## Contents` is a grouped two-level index, and the seven overlapping notation-rejection bullets are folded into one table with a `Write instead` column. The nested-count tag-ownership rule moved to `RollResult`, where the fields it describes live ([#293](https://github.com/edloidas/roll-parser/issues/293))
+
 ## [3.1.0] - 2026-08-08
 
 ### Added
@@ -217,7 +251,9 @@ Dice mechanics (Stage 2):
 - Dice count safety limit via `maxDice` option (default 10,000), enforced across the whole expression to prevent DoS via additive groups like `5000d6+5000d6` ([#19](https://github.com/edloidas/roll-parser/issues/19))
 - Parser and evaluator correctness: duplicate `kept` modifier entries, implicit modifier count defaulting to 1 (`4d6kh` → `4d6kh1`), `critical` flag suppression when `sides === 1`, negative `--seed` CLI values ([#21](https://github.com/edloidas/roll-parser/issues/21))
 
-[Unreleased]: https://github.com/edloidas/roll-parser/compare/v3.1.0...HEAD
+[Unreleased]: https://github.com/edloidas/roll-parser/compare/v3.2.1...HEAD
+[3.2.1]: https://github.com/edloidas/roll-parser/releases/tag/v3.2.1
+[3.2.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.2.0
 [3.1.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.1.0
 [3.0.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.0.0
 [3.0.0-beta.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.0.0-beta.0

package/MIGRATION.md

@@ -1,8 +1,227 @@
 # Migration notes
 
-Newest first. [Upgrading from 3.0.0 to 3.1.0](#upgrading-from-300-to-310) ·
-[Migrating from v2 to v3](#migrating-from-v2-to-v3) ·
-[Upgrading from a v3 pre-release](#upgrading-from-a-v3-pre-release)
+Newest first.
+
+- [Upgrading from 3.1.0 to 3.2.0](#upgrading-from-310-to-320)
+- [Upgrading from 3.0.0 to 3.1.0](#upgrading-from-300-to-310)
+- [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+- [Upgrading from a v3 pre-release](#upgrading-from-a-v3-pre-release)
+
+## Upgrading from 3.1.0 to 3.2.0
+
+Nothing was removed from the API, no type changed, and the seed → dice mapping
+is untouched — the same seed and notation roll the same faces they did in
+3.1.0. What moves falls in two buckets. Several group forms that used to
+evaluate now throw a parse error — `{3, 5, 7}>=4`, `{2d6+3}kh2`, `{2d6*2}kh2`,
+`{3d20+5}>=21`, and `{2d6, 2d8}kh1>=4` — each listed below with a rewrite. The
+rest are values that moved: `initialResult` on `!p` dice, one `vs` degree, the
+`expression` and `rendered` strings, and the totals and tags of nested and
+grouped success counts.
+
+**`!p` continuation dice now carry `initialResult`.** A penetrating explosion
+stores `raw - 1` on each die it appends, and used to record the face it
+replaced nowhere, so the `initialResult ?? result` idiom `DieResult` documents
+returned the decremented value and a natural 20 was indistinguishable from a
+19.
+
+```typescript
+import { roll } from 'roll-parser';
+import { createMockRng } from 'roll-parser/testing';
+
+const die = roll('1d20!p', { rng: createMockRng([20, 20, 5]) }).rolls[1];
+
+die.result; // 19
+die.initialResult; // 20 — was `undefined`
+```
+
+Standard `!` is unchanged: its appended dice store what they rolled, so they
+still carry no `initialResult`. Two things can bite:
+
+- **Deep-equality assertions against a `!p` pool fail.** The appended dice gain
+  a field. Assert on what you care about, or add `initialResult` to the
+  expected die.
+- **`--json` and `JSON.stringify(result)` payloads grow** by one number per
+  appended `!p` die. Expressions without `!p` are unchanged.
+
+**Bare `cs`/`cf` judges a `!p` die by the face it rolled.** The side you do not
+override reads the natural face, which now exists on these dice — so a
+continuation that rolled its maximum is critical even though it displays one
+less, matching the flags plain `1d6!p` already set.
+
+```typescript
+const result = roll('1d6!pcf>5', { rng: createMockRng([6, 6, 3]) });
+
+result.rendered; // '1d6!pcf>5[6, 5, 2] = 13'
+result.rolls[1].critical; // true — was `false`, judged by the stored 5
+```
+
+If you assert `critical` or `fumble` on `!p` continuation dice, re-derive the
+expected flag from `initialResult ?? result`. Order stops mattering here:
+`1d6cf>5!p` and `1d6!pcf>5` now agree, where 3.1.0's README documented them as
+disagreeing, and [Modifiers](README.md#modifiers) is rewritten to match. An
+explicit threshold is still a predicate over a die's current `result`, so `!!`,
+`minN`, and `maxN` remain order-sensitive.
+
+**Adjacent bare modifiers keep a space in `expression` and `rendered`.** `cs`,
+`cf`, `s`, and `sd` with no threshold or count end in a letter the lexer scans
+as an identifier, so the normalized form used to re-lex as one token and no
+longer round-tripped through `parse`.
+
+```typescript
+roll('1d20cs cf', { rng: createMockRng([20]) }).expression; // '1d20cs cf' — was '1d20cscf'
+roll('4d6 s kh2', { rng: createMockRng([1, 2, 3, 4]) }).rendered;
+// '4d6s[~~1~~, ~~2~~, 3, 4] = 7' — the prefix was '4d6skh2'
+```
+
+Only those four codes are affected; `4dF` and `!p` end in letters but are their
+own tokens, so they stay flush. Snapshot assertions over `expression` or
+`rendered` for an affected expression need re-recording.
+
+**One `vs` case stops discarding its natural face.** Only `vs` expressions
+whose roll side both appends explosion dice and clamps them — `!` or `!!`
+combined with `minN`/`maxN` — are affected: a clamped continuation used to be
+counted as a second primary d20, and two primaries suppress the natural 20 /
+natural 1 step. Without the clamp (`1d20! vs 30`) the continuation never looked
+like a primary, and those degrees are unchanged.
+
+```typescript
+import { DegreeOfSuccess } from 'roll-parser';
+
+const result = roll('1d20!min5 vs 30', { rng: createMockRng([20, 2, 12]) });
+
+result.natural; // 20 — was `undefined`
+result.degree === DegreeOfSuccess.Success; // true — was `Failure`
+```
+
+If you pinned `natural` or `degree` on such a roll, re-record it.
+
+**Success counting a dice-less group is now a parse error.** `{3, 5, 7}>=4`
+used to return the group's sum with `successes: 0`, so the
+`successCount.total === successes - failures` invariant the README offers read
+`15 === 0`. There are no dice to tally, and whether a group's units should be
+its subtotals is undecided, so the form is refused instead.
+
+```typescript
+roll('{3, 5, 7}>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was 15
+roll('{3, 5, 7}kh1>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was 7
+roll('{3, 0d6}>=4').total; // 0 — was 3
+```
+
+Groups holding at least one pool are untouched — `{3, 1d6}>=4` counts the `1d6`
+exactly as it did. `0d6>=4` also still parses and totals 0; only targets that
+can never roll a die are rejected. There is no in-notation rewrite for a
+literal-only group: replace the literals with the pool they stood in for
+(`3d6>=4`), or drop the count and keep the group's sum (`{3, 5, 7}`).
+
+**A second success count re-scores the pool instead of adding to it.** Group
+braces let one count wrap another (`{4d6>=5f1}<=2f6`), which the parse-time
+reject on a direct `4d6>=5>=1` never reached. The inner pass used to leave its
+tags behind, so a die could come back both `'success'` and `'failure'` and the
+top-level counts stopped describing the total. The outermost count now owns the
+tags outright.
+
+```typescript
+const result = roll('{4d6>=5f1}<=2f6', { rng: createMockRng([6, 5, 2, 1]) });
+
+result.total; // 1
+result.successes; // 2 — was 4
+result.failures; // 1 — was 0
+result.rendered; // '{4d6>=5f1}<=2f6[__6__, 5, **2**, **1**] = 1'
+```
+
+`total` never moved — it always came from the outermost count, so a test
+asserting only `total` needs no change. What changed is `successes`,
+`failures`, `rolls[].modifiers`, and `rendered`, which now agree with it, so
+`successCount.total === successes - failures` holds again. A lone
+count is untouched, and so is a nested pair whose thresholds agree
+(`{4d6>=5}>=5`). Dropped dice come out untagged; only the DC side of a `vs`
+keeps tags from an inner count, since no pool pass may tally it.
+
+**Keep/drop on a single-sub-roll group now takes added dice terms only.** The
+flat-pool form totals the faces it kept, so any term in the sub-roll that is not
+an added die face was discarded from the total with no error and no marker.
+`{2d6+3}kh2` lost the `+3`, and `{2d6-1d4}kh3` — which drops nothing — flipped
+the `1d4` from `-3` to `+3`. The parser already refused `(2d6+3)kh2` for exactly
+this reason; the brace form now does too.
+
+```typescript
+roll('{2d6+3}kh2', { rng: createMockRng([4, 5]) }); // throws 'INVALID_KEEP_DROP_TARGET' — was 9
+roll('{2d6-1d4}kh3', { rng: createMockRng([4, 5, 3]) }); // throws 'INVALID_KEEP_DROP_TARGET' — was 12
+roll('{2d6*2}kh2', { rng: createMockRng([4, 5]) }); // throws 'INVALID_KEEP_DROP_TARGET'
+roll('{2d6+0}kh2', { rng: createMockRng([4, 5]) }); // throws 'INVALID_KEEP_DROP_TARGET' — identity terms too
+roll('{4d6+2d8}kh3', { rng: createMockRng([6, 6, 6, 1, 8, 1]) }).total; // 20 — unchanged
+```
+
+Also newly rejected, same cause: a function-wrapped pool (`{abs(1d6-1d8)}kh1`),
+and a success count, which returned the face sum rather than the tally.
+`{4d6>=5}kh1` throws `INVALID_SUCCESS_COUNT_TARGET`, not the keep/drop code — a
+single-sub-roll group used to hide the count from the reject that `(4d6>=5)kh1`
+has always hit, and both spellings now report the same thing.
+
+The check is structural rather than arithmetic, so identity terms are refused
+with the rest even though their total was already right: `{2d6+0}kh2`,
+`{2d6*1}kh2`, and `{2d6+1d8-0}kh3` all throw.
+
+Additive pools are the form this syntax exists for and are untouched —
+`{4d6+2d8}kh3`, `{2d6kh1+1d8}kh2`, `{{1d6, 1d8}+2d6}kh2`. Multi-sub-roll groups
+never had the bug, since keep/drop compares subtotals there: `{2d6+3, 1d8}kh1`
+still works. To keep a rejected expression, move the arithmetic outside the
+selection (`{2d6}kh2+3`) or give each term its own sub-roll.
+
+**Success counting a multi-sub-roll group now scores subtotals, not dice.**
+`{2d6, 2d6}>=10` used to compare all four faces against 10 and find nothing,
+while `{2d6, 2d6}kh1` on the same node saw two compound dice worth 11 and 3.
+Roll20 counts one success per sub-roll total, and that is what the count does
+now.
+
+```typescript
+const result = roll('{2d6, 2d6}>=10', { rng: createMockRng([6, 5, 2, 1]) });
+
+result.total; // 1 — was 0
+result.successes; // 1 — was 0
+result.rendered; // '{2d6[6, 5], 2d6[2, 1]}>=10 = 1'
+```
+
+Four things move with it:
+
+- **`rendered`** shows each sub-roll's own bracket instead of one flat pool —
+  the dice are no longer the units.
+- **`rolls[].modifiers`** comes back untagged: no `'success'` or `'failure'` on
+  any die, for the same reason. Read `successes` / `failures` instead.
+- **`fT` thresholds** score subtotals too, so `{4d6+2d8, 3d20+3,
+  5d10+1}>=40f<=10` weighs three subtotals rather than 21 faces.
+- **A literal sub-roll** is a subtotal like any other, so it is scored rather
+  than skipped.
+
+```typescript
+const literal = roll('{3, 1d6}>=4f<=3', { rng: createMockRng([6]) });
+
+literal.successes; // 1
+literal.failures; // 1 — was 0
+literal.total; // 0 — was 1
+```
+
+Single-sub-roll groups (`{4d6}>=5`, `{2d6+1d8}>=5`) are the flat-pool form and
+are unchanged.
+
+**Two group spellings of a success count are now parse errors.** Both used to
+reach the flat counter with the subtotals already gone.
+
+```typescript
+roll('{3d20+5}>=21'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was a count of bare faces
+roll('{2d6, 2d8}kh1>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was a count of loose dice
+roll('({2d6, 2d8})>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET'
+```
+
+- **`{3d20+5}>=21`** hits the single-sub-roll rule keep/drop already has: that
+  form compares one face at a time, so a scalar term never reaches the
+  comparison. A scaled or function-wrapped pool goes with it — `{2d6*2}>=4` and
+  `{floor(2d6/2)}>=2` throw too, exactly as `{2d6*2}kh2` does. To keep it, fold
+  the scalar into the threshold: `3d20>=16` counts the same dice.
+- **`{2d6, 2d8}kh1>=4`** covers every way a multi-sub-roll group can arrive
+  somewhere other than as the count's direct target — `{{2d6, 2d8}}>=4` and
+  `({2d6, 2d8})>=4` throw the same code. To keep it, count the group directly:
+  `{2d6, 2d8}>=4`.
 
 ## Upgrading from 3.0.0 to 3.1.0
 
@@ -48,8 +267,8 @@ group sub-roll nested inside another one used to emit mismatched delimiters —
 `{{(1d6[1]), 1d8[4]}, ({(1d10[1]), 1d12[3]})}`. Anything parsing that output
 should be reading `--json` instead.
 
-**New, optional: `roll-parser/render`.** A subpath export whose
-`renderBreakdown(result, marks?)` rebuilds the breakdown from `result.parts`
+**New, optional: `renderBreakdown` from `roll-parser/render`.** A subpath
+export whose `renderBreakdown(result, marks?)` rebuilds the breakdown from `result.parts`
 with markers you choose, so you no longer have to regex the markdown out of
 `rendered`. With no marks its output is byte-identical to `rendered`, which
 makes it a drop-in starting point:
@@ -100,9 +319,7 @@ classes. v3 has `roll(notation, options)` for the common path, and
 | `convert(obj)`, `Roll`, `WodRoll`, `Result` | removed — there are no roll-description objects to build or convert |
 
 **Result fields moved.** v2 returned `Result { notation, value, rolls }` where
-`rolls` was a plain `number[]`. The v3 snippets below draw from
-`createMockRng` (exported by `roll-parser/testing`) so their numbers are exact
-rather than whatever the dice happened to do:
+`rolls` was a plain `number[]`.
 
 <!-- readme-test: skip -->
 ```typescript