From 7470eea1a8abaca718011dd95420be4020693c0b Mon Sep 17 00:00:00 2001 From: Mikita Taukachou Date: Sun, 29 Mar 2026 22:31:16 +0200 Subject: [PATCH] docs: update documentation for v3 #23 Stripped README to minimal docs: description, installation, single `roll()` usage example, CLI, and known limitations. Removed Development, Architecture, Project Structure, and Supported Systems sections. Updated status from "v3 in Development" to "v3 Alpha" with Stage 1 marked complete. Marked GAPS.md findings #9, #10, #11, #31, #34 as resolved and updated #22/#24 to closed. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/docs/GAPS.md | 35 ++++++++++--------------- README.md | 61 +++++--------------------------------------- 2 files changed, 20 insertions(+), 76 deletions(-) diff --git a/.claude/docs/GAPS.md b/.claude/docs/GAPS.md index 431baf4..d60993a 100644 --- a/.claude/docs/GAPS.md +++ b/.claude/docs/GAPS.md @@ -63,24 +63,19 @@ correctly uses `--target node`. ## High — Documentation -### 9. CONTRIBUTING.md is entirely stale (v2-era) *(→ [#23](https://github.com/edloidas/roll-parser/issues/23))* +### ~~9. CONTRIBUTING.md is entirely stale (v2-era)~~ *(→ [#23](https://github.com/edloidas/roll-parser/issues/23))* ✓ Resolved -- Recommends emoji-prefixed commits (`:art:`, `:bug:`) which contradicts - CLAUDE.md Conventional Commits format -- No mention of Bun, TypeScript, Biome, or any v3 tooling -- References generic "coding conventions" with no link to actual standards -- PR workflow does not match CLAUDE.md template +File deleted — will be rewritten when the project is ready for external +contributions. -### 10. README says Stage 1 is "In Progress" — it is complete *(→ [#23](https://github.com/edloidas/roll-parser/issues/23))* +### ~~10. README says Stage 1 is "In Progress" — it is complete~~ *(→ [#23](https://github.com/edloidas/roll-parser/issues/23))* ✓ Resolved -All Stage 1 features are implemented with 305 passing tests. The status badge -is misleading. +Status section updated to reflect Stage 1 completion (327 tests passing). -### 11. README `rendered` format example is incorrect *(→ [#23](https://github.com/edloidas/roll-parser/issues/23))* +### ~~11. README `rendered` format example is incorrect~~ *(→ [#23](https://github.com/edloidas/roll-parser/issues/23))* ✓ Resolved -Shows `"4d6kh3[6,5,3,2] = 14"` but actual output is -`"4d6[3, 6, ~~3~~, 3] = 12"` — no modifier suffix in rendered, spaces after -commas, and strikethrough for dropped dice. +Detailed usage examples removed from README. Minimal usage section no longer +includes `rendered` output. ## Medium — Code Quality @@ -190,10 +185,9 @@ sets `lineWidth: 100`. ## Low — Minor Issues -### 31. `PLAN.md` is stale *(→ [#23](https://github.com/edloidas/roll-parser/issues/23), fixed in 27d9cb6)* +### ~~31. `PLAN.md` is stale~~ *(→ [#23](https://github.com/edloidas/roll-parser/issues/23), fixed in 27d9cb6)* ✓ Resolved -Still says Phase 0 is "Current Step — Blocking" even though all phases are -complete. +Phase markers updated in commit 27d9cb6. ### 32. `tsconfig.json` has confusing `noEmit: true` with `declaration: true` *(→ [#22](https://github.com/edloidas/roll-parser/issues/22))* @@ -206,10 +200,9 @@ the CLI. A separate `tsconfig.build.json` would be cleaner. If someone runs `tsc` without `--noEmit`, declarations would be emitted into the source tree. -### 34. Issue #1 from v2 still open *(→ [#23](https://github.com/edloidas/roll-parser/issues/23), already closed)* +### ~~34. Issue #1 from v2 still open~~ *(→ [#23](https://github.com/edloidas/roll-parser/issues/23), already closed)* ✓ Resolved -"More functions similar to Roll20" from 2017 is still open. Should be closed -or updated to reference the v3 roadmap (Stage 2/3 features). +Issue #1 closed. ### 35. `bin` field uses shorthand form *(→ [#22](https://github.com/edloidas/roll-parser/issues/22))* @@ -244,9 +237,9 @@ Findings grouped into GitHub issues: | [#19](https://github.com/edloidas/roll-parser/issues/19) | `fix: add dice count safety limit` | #1, #12 | ✓ Closed | | [#20](https://github.com/edloidas/roll-parser/issues/20) | `ci: fix test pipeline and add quality gates` | #2, #24–#27 | ✓ Closed | | [#21](https://github.com/edloidas/roll-parser/issues/21) | `fix: parser and evaluator correctness` | #3, #4, #19, #21, #23 | ✓ Closed | -| [#22](https://github.com/edloidas/roll-parser/issues/22) | `build: fix npm publish artifacts` | #6–#8, #28, #29, #32, #33, #35 | Open | +| [#22](https://github.com/edloidas/roll-parser/issues/22) | `build: fix npm publish artifacts` | #6–#8, #28, #29, #32, #33, #35 | ✓ Closed | | [#23](https://github.com/edloidas/roll-parser/issues/23) | `docs: update documentation for v3` | #9–#11, #31, #34 | Open | -| [#24](https://github.com/edloidas/roll-parser/issues/24) | `refactor: clean up public API surface` | #13–#16, #20, #22, #30, #37, #38 | Open | +| [#24](https://github.com/edloidas/roll-parser/issues/24) | `refactor: clean up public API surface` | #13–#16, #20, #22, #30, #37, #38 | ✓ Closed | | [#25](https://github.com/edloidas/roll-parser/issues/25) | `epic: implement Stage 2 — system compatibility` | #18 + Stage 2 roadmap | Open | | [#30](https://github.com/edloidas/roll-parser/issues/30) | `epic: implement Stage 3 — advanced features` | Stage 3 roadmap | Open | diff --git a/README.md b/README.md index 74375e1..ef95aff 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ TypeScript-first, Bun-optimized, Pratt parser architecture. ## Status -> **v3 in Development** - Complete architectural rewrite in progress. +> **v3 Alpha** — Stage 1 (Core Engine) is complete with 300+ tests. +> Stages 2–3 are planned. > > For production use, install [v2.3.2](https://www.npmjs.com/package/roll-parser/v/2.3.2). @@ -45,78 +46,28 @@ TypeScript-first, Bun-optimized, Pratt parser architecture. ## Installation ```bash -# When v3 is released bun add roll-parser npm install roll-parser ``` -## Usage (v3 API Preview) +## Usage ```typescript -import { roll, parse } from 'roll-parser'; +import { roll } from 'roll-parser'; -// Simple roll const result = roll('4d6kh3'); -console.log(result.total); // e.g., 14 -console.log(result.rolls); // Individual die results -console.log(result.rendered); // e.g., "4d6[~~2~~, 4, 5, 6] = 15" - -// With seeded RNG for reproducibility -const seeded = roll('2d20', { seed: 'my-seed' }); - -// Parse without rolling (for inspection) -const ast = parse('2d6+5'); +console.log(result.total); // e.g., 14 +console.log(result.notation); // "4d6kh3" ``` ### CLI ```bash -# Roll dice from command line roll-parser 2d6+3 roll-parser 4d6kh3 roll-parser --help ``` -## Development - -```bash -bun install # Install dependencies -bun check:fix # Type check + lint + format -bun test # Run tests -bun run build # Build library -bun release:dry # Validate release -``` - -## Architecture - -Built with a Pratt parser for: - -- **Clean precedence handling** - Operator binding power, not grammar rules -- **Easy extensibility** - Add new modifiers without restructuring -- **Optimal performance** - Target <1ms for complex expressions -- **Type safety** - Strict TypeScript, no `any` - -### Project Structure - -``` -src/ -├── lexer/ # Tokenization (d, kh, kl, dh, dl, numbers, operators) -├── parser/ # Pratt parser with AST generation -├── evaluator/ # AST evaluation with modifier handling -├── rng/ # Seedable random number generation -├── cli/ # Command-line interface -└── index.ts # Public API exports -``` - -## Supported Systems - -| System | Notation Examples | Stage | -|--------|-------------------|-------| -| D&D 5e | `2d6`, `1d20+5`, `4d6kh3` | 1 | -| Pathfinder 2e | `1d20+10 vs 25` | 2 | -| World of Darkness | `10d10>=6f1` | 2 | -| Savage Worlds | `1d6!` | 2 | - ## Known Limitations - **`4d6d1` parses as nested dice, not "drop 1".** The bare `d` token is always