roll-parser 3.0.0-beta.0 → 3.0.0

package/package.json

@@ -1,14 +1,12 @@
 {
   "name": "roll-parser",
-  "version": "3.0.0-beta.0",
-  "description": "High-performance dice notation parser for tabletop RPGs. TypeScript-first, Bun-optimized.",
+  "version": "3.0.0",
+  "description": "High-performance dice notation parser for tabletop RPGs. TypeScript-first, runs on Node, Bun, and browsers with zero dependencies.",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "bin": {
-    "roll-parser": "./dist/cli.js"
+    "roll-parser": "./dist/cli/index.js"
   },
-  "sideEffects": false,
+  "sideEffects": ["./dist/cli/index.js"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,21 +18,33 @@
     },
     "./package.json": "./package.json"
   },
+  "unpkg": "./dist/index.js",
+  "jsdelivr": "./dist/index.js",
   "files": [
     "dist",
     "src",
     "CHANGELOG.md",
-    "!src/**/*.test.ts"
+    "MIGRATION.md",
+    "!src/**/*.test.ts",
+    "!src/test-helpers.ts"
   ],
   "keywords": [
     "parser",
     "dice",
+    "dice-notation",
+    "dice-roller",
+    "dice-parser",
     "roll",
     "rpg",
+    "ttrpg",
+    "tabletop",
     "dnd",
     "d20",
-    "pratt-parser",
     "typescript",
+    "esm",
+    "browser",
+    "zero-dependency",
+    "cli",
     "bun"
   ],
   "homepage": "https://github.com/edloidas/roll-parser#readme",
@@ -42,7 +52,7 @@
     "url": "https://github.com/edloidas/roll-parser/issues"
   },
   "license": "MIT",
-  "author": "Mikita Taukachou <edloidas@gmail.com> (https://edloidas.com)",
+  "author": "Mikita Taukachou <edloidas@gmail.com> (https://edloidas.io)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/edloidas/roll-parser.git"
@@ -50,43 +60,82 @@
   "publishConfig": {
     "access": "public"
   },
+  "workspaces": ["scripts/browser-smoke", "scripts/docs"],
   "scripts": {
-    "typecheck": "tsc --noEmit",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint --write .",
-    "format": "biome format --write .",
-    "format:check": "biome format .",
-    "check": "bun typecheck && bun lint && bun format:check",
-    "check:fix": "bun typecheck && bun lint:fix && bun format",
+    "prepare": "git rev-parse --git-dir > /dev/null 2>&1 && git config core.hooksPath .githooks || exit 0",
+    "typecheck": "tsc --noEmit && bun run build && tsc --noEmit -p site/tsconfig.json && tsc --noEmit -p scripts/tsconfig.json && tsc --noEmit -p bench/tsconfig.json",
+    "check": "bun typecheck && biome check .",
+    "check:fix": "bun typecheck && biome check --write .",
     "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: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",
+    "generate:version": "bun scripts/generate-version.ts",
+    "clean": "rm -rf dist",
+    "build": "bun scripts/build.ts",
     "check:package": "attw --pack . --profile esm-only && publint",
-    "bench": "bun run bench/roll.bench.ts",
+    "check:size": "size-limit",
+    "bench": "bun run bench/index.bench.ts",
+    "bench:lex": "bun run bench/lex.bench.ts",
+    "bench:parse": "bun run bench/parse.bench.ts",
+    "bench:evaluate": "bun run bench/evaluate.bench.ts",
+    "bench:roll": "bun run bench/roll.bench.ts",
+    "bench:json": "bun run scripts/bench-json.ts",
+    "bench:competitors": "cd bench/competitors && bun install && bun run all",
+    "site:build": "bun run build && bun scripts/build-site.ts",
+    "site:check": "bun scripts/check-site.ts",
+    "site:dev": "bun run build && bun ./site/index.html ./site/reference.html",
+    "site:preview": "bun scripts/serve-site.ts",
     "test": "bun test",
-    "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 --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 run check:package && bun test",
+    "validate": "bun run check && bun run build && bun run check:package && bun run check:size && bun run site:build && bun run site:check && bun test:ci",
+    "release:dry": "bun run check:version && bun run check:changelog && bun audit --audit-level=high && bun run clean && bun run validate",
     "prepublishOnly": "bun run release:dry"
   },
+  "nano-staged": {
+    "*.{ts,tsx}": "biome check --write --no-errors-on-unmatched"
+  },
+  "size-limit": [
+    {
+      "name": "index.js (full library)",
+      "path": "dist/index.js",
+      "limit": "12.5 kB"
+    },
+    {
+      "name": "index.js — { parse }",
+      "path": "dist/index.js",
+      "import": "{ parse }",
+      "limit": "6 kB"
+    },
+    {
+      "name": "index.js — { roll }",
+      "path": "dist/index.js",
+      "import": "{ roll }",
+      "limit": "12 kB"
+    },
+    {
+      "name": "testing.js — { createMockRng }",
+      "path": "dist/testing.js",
+      "import": "{ createMockRng }",
+      "limit": "250 B"
+    }
+  ],
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.4",
-    "@biomejs/biome": "^2.4.9",
-    "@types/bun": "^1.3.0",
-    "fast-check": "^4.6.0",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.5.6",
+    "@size-limit/preset-small-lib": "^13.0.2",
+    "@types/bun": "^1.3.14",
+    "esbuild": "^0.28.1",
+    "fast-check": "^4.9.0",
     "mitata": "^1.0.34",
-    "publint": "^0.3.21",
-    "typescript": "^6.0.2"
+    "nano-staged": "^1.0.2",
+    "publint": "^0.3.22",
+    "size-limit": "^13.0.2",
+    "typescript": "^7.0.2"
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.9"
   },
   "engines": {
-    "node": ">= 22.0.0"
+    "node": ">=22.12.0"
   }
 }

package/src/cli/args.ts

@@ -12,6 +12,7 @@
 export type CliArgs = {
   notation: string | undefined;
   verbose: boolean;
+  json: boolean;
   seed: string | undefined;
   showHelp: boolean;
   showVersion: boolean;
@@ -22,6 +23,46 @@ export type CliArgs = {
  */
 export type ParseArgsResult = { ok: true; args: CliArgs } | { ok: false; error: string };
 
+/** Argument that stops option parsing — everything after it is notation. */
+const TERMINATOR = '--';
+
+/** Defaults every parse starts from. */
+const BASE_ARGS: CliArgs = {
+  notation: undefined,
+  verbose: false,
+  json: false,
+  seed: undefined,
+  showHelp: false,
+  showVersion: false,
+};
+
+/**
+ * Finds `--help` / `--version` anywhere before the `--` terminator. Help wins
+ * over version regardless of order, and both win over usage errors — a user
+ * who mistyped an option is asking for the manual, not for a diagnostic.
+ */
+function findInformationalFlag(argv: string[]): 'help' | 'version' | undefined {
+  let flag: 'help' | 'version' | undefined;
+
+  for (const arg of argv) {
+    if (arg === TERMINATOR) break;
+    if (arg === '--help' || arg === '-h') return 'help';
+    if (arg === '--version') flag = 'version';
+  }
+
+  return flag;
+}
+
+/**
+ * True for an argument that starts with `-` yet reads as notation rather than
+ * an option: negative numbers (`-3`) and negative-prefixed expressions
+ * (`-d6`, `-D6`, `-dF`, `-(2d6)`, `-{2d6}`, `-@str`). A fallback for users who
+ * do not reach for `--`; `--` remains the unambiguous form.
+ */
+function isNegativeNotation(arg: string): boolean {
+  return arg.length > 1 && /^[\ddD({@]/.test(arg.slice(1));
+}
+
 /**
  * Parses a raw argument array into typed CLI options.
  *
@@ -29,24 +70,38 @@ export type ParseArgsResult = { ok: true; args: CliArgs } | { ok: false; error:
  * @returns Parsed result or an error message for usage errors
  */
 export function parseArgs(argv: string[]): ParseArgsResult {
+  const informational = findInformationalFlag(argv);
+  if (informational != null) {
+    return {
+      ok: true,
+      args: {
+        ...BASE_ARGS,
+        showHelp: informational === 'help',
+        showVersion: informational === 'version',
+      },
+    };
+  }
+
   let verbose = false;
+  let json = false;
   let seed: string | undefined;
-  let showHelp = false;
-  let showVersion = false;
   const positional: string[] = [];
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i] as string;
 
-    if (arg === '--help' || arg === '-h') {
-      showHelp = true;
-    } else if (arg === '--version') {
-      showVersion = true;
+    if (arg === TERMINATOR) {
+      positional.push(...argv.slice(i + 1));
+      break;
     } else if (arg === '--verbose' || arg === '-v') {
       verbose = true;
+    } else if (arg === '--json') {
+      json = true;
     } else if (arg === '--seed') {
+      // A seed is an opaque string, so any non-empty next argument counts:
+      // `--seed -abc` is a valid seed, not a missing value.
       const next = argv[i + 1];
-      if (next === undefined || (next.startsWith('-') && !/^-\d/.test(next))) {
+      if (next == null || next === '') {
         return { ok: false, error: 'Missing value for --seed' };
       }
       seed = next;
@@ -59,15 +114,16 @@ 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 && !/^[\ddD(]/.test(arg.slice(1))) {
-      // Negative prefix notation (-3, -d6, -D6, -dF, -(2d6)) stays positional
+    } else if (arg.startsWith('-') && !isNegativeNotation(arg)) {
       return { ok: false, error: `Unknown option: ${arg}` };
     } else {
       positional.push(arg);
     }
   }
 
+  // Joined, not separate rolls — a shell splits `roll-parser 2d6 + 3` into three
+  // words and the user means one expression.
   const notation = positional.length > 0 ? positional.join(' ') : undefined;
 
-  return { ok: true, args: { notation, verbose, seed, showHelp, showVersion } };
+  return { ok: true, args: { ...BASE_ARGS, notation, verbose, json, seed } };
 }

package/src/cli/format.ts

@@ -8,17 +8,36 @@
 
 import type { RollResult } from '../types.js';
 
+/**
+ * Output mode selectors for {@link formatResult}.
+ */
+export type FormatOptions = {
+  /** Emit the whole result as compact JSON. Takes precedence over `verbose`. */
+  json?: boolean;
+  /** Show the detailed roll breakdown instead of the bare total. */
+  verbose?: boolean;
+};
+
 /**
  * Formats a roll result for terminal display.
  *
  * In normal mode, returns just the total. In verbose mode, returns the
- * rendered breakdown with terminal-safe formatting for dropped dice.
+ * rendered breakdown with terminal-safe formatting for dropped dice. In JSON
+ * mode, returns the complete `RollResult` — including the structured `parts`
+ * tree — as a single-line `JSON.stringify` payload, where `degree` appears as
+ * its numeric `DegreeOfSuccess` value.
  *
  * @param result - The roll result to format
- * @param verbose - Whether to show the detailed breakdown
+ * @param options - Output mode; JSON wins when combined with verbose
  * @returns Formatted string for terminal output
  */
-export function formatResult(result: RollResult, verbose: boolean): string {
+export function formatResult(result: RollResult, options: FormatOptions = {}): string {
+  const { json = false, verbose = false } = options;
+
+  if (json) {
+    return JSON.stringify(result);
+  }
+
   if (!verbose) {
     return String(result.total);
   }

package/src/cli/index.ts

@@ -3,90 +3,33 @@
 /**
  * CLI entry point for roll-parser.
  *
+ * Owns the process-level wiring only; the command itself lives in
+ * `./main.js` so it stays testable without spawning a subprocess.
+ *
  * @module cli/index
  */
 
-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}
-
-Usage: roll-parser <notation> [options]
-
-Options:
-  -h, --help       Show this help message
-  --version        Show version number
-  -v, --verbose    Show detailed roll breakdown
-  --seed <value>   Use seed for reproducible rolls
-
-Examples:
-  roll-parser 2d6+3
-  roll-parser 4d6kh3 --verbose
-  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));
-
-  if (!parsed.ok) {
-    process.stderr.write(`Error: ${parsed.error}\n`);
-    process.stderr.write('Run "roll-parser --help" for usage.\n');
-    process.exitCode = 2;
-    return;
-  }
-
-  const { args } = parsed;
-
-  if (args.showHelp) {
-    process.stdout.write(HELP_TEXT);
-    return;
-  }
-
-  if (args.showVersion) {
-    process.stdout.write(`${VERSION}\n`);
-    return;
-  }
-
-  if (args.notation == null) {
-    process.stderr.write('Error: No dice notation provided.\n');
-    process.stderr.write('Run "roll-parser --help" for usage.\n');
-    process.exitCode = 2;
-    return;
-  }
-
-  try {
-    const options = args.seed != null ? { seed: args.seed } : {};
-    const result = roll(args.notation, options);
-    const output = formatResult(result, args.verbose);
-    process.stdout.write(`${output}\n`);
-  } catch (error) {
-    if (isRollParserError(error)) {
-      process.stderr.write(`Error: ${error.message}\n`);
-      writeErrorContext(args.notation, error);
-      process.exitCode = 1;
-      return;
-    }
-    throw error;
-  }
-}
-
-main();
+import { main } from './main.js';
+
+// Declared locally because the library build sets `types: []` — runtime globals
+// are type errors everywhere, and this is the one place `process` is legitimate.
+declare const process: {
+  argv: string[];
+  exitCode: number | undefined;
+  stdout: { write(text: string): void };
+  stderr: { write(text: string): void };
+};
+
+const exitCode = main({
+  argv: process.argv.slice(2),
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+});
+
+// Left unset on success — assigning 0 would clobber an exit code a surrounding
+// runtime hook may already have set.
+if (exitCode !== 0) process.exitCode = exitCode;

package/src/cli/main.ts

@@ -0,0 +1,129 @@
+/**
+ * CLI command implementation for roll-parser.
+ *
+ * Split out of `index.ts` so `main` and `writeErrorContext` can run
+ * in-process under the test runner — the shebang entry point stays a thin
+ * wrapper that owns `process.argv`, the real streams, and `process.exitCode`.
+ *
+ * @module cli/main
+ */
+
+import { getErrorSpan, 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}
+
+Usage: roll-parser [options] [--] <notation>
+
+Options:
+  -h, --help       Show this help message
+  --version        Show version number
+  -v, --verbose    Show detailed roll breakdown
+  --json           Print the whole result as compact JSON (wins over --verbose)
+  --seed <value>   Use seed for reproducible rolls
+  --               Treat every following argument as notation
+
+JSON output:
+  Emits the complete result, including the structured "parts" tree. The
+  "degree" field (DegreeOfSuccess) serializes as a number: 0 critical failure,
+  1 failure, 2 success, 3 critical success. Errors stay plain text on stderr.
+
+Exit codes:
+  0  Success
+  1  Roll or parse error
+  2  Usage error
+
+Examples:
+  roll-parser 2d6+3
+  roll-parser 4d6kh3 --verbose
+  roll-parser 4d6dl1 --seed "character-str"
+  roll-parser "1d20+7 vs 25" --json
+  roll-parser -- -1d6+3
+`;
+
+/** Sink for one stream's worth of CLI output. */
+export type WriteFn = (text: string) => void;
+
+/** Everything `main` needs from the host process. */
+export type CliEnv = {
+  /** Arguments after the interpreter and script path (`process.argv.slice(2)`). */
+  argv: string[];
+  stdout: WriteFn;
+  stderr: WriteFn;
+};
+
+/**
+ * Prints the notation with a caret under the error position. `getErrorSpan`
+ * normalizes the lexer/parser `position` and the evaluator `start`/`end`
+ * shapes, so no duck-typing is needed here. Skipped for multi-line notations
+ * and out-of-range positions to keep the caret honest.
+ */
+export function writeErrorContext(notation: string, error: unknown, write: WriteFn): void {
+  const span = getErrorSpan(error);
+  if (span == null) return;
+  if (notation.includes('\n') || span.start > notation.length) return;
+
+  // Code points, not UTF-16 units — an astral character ('🎲') is two units but
+  // one column, and counting units shifts the caret right.
+  const column = [...notation.slice(0, span.start)].length;
+
+  write(`  ${notation}\n`);
+  write(`  ${' '.repeat(column)}^\n`);
+}
+
+/**
+ * Runs one CLI invocation and returns the process exit code: `0` on success,
+ * `1` for a roll-parser error, `2` for a usage error. Anything that is not a
+ * `RollParserError` propagates so the runtime reports it with a stack.
+ *
+ * `--json` swaps the success payload only — diagnostics stay plain text on
+ * stderr and the exit codes are identical, so scripts can branch on the code
+ * before parsing stdout.
+ */
+export function main(env: CliEnv): number {
+  const { argv, stdout, stderr } = env;
+  const parsed = parseArgs(argv);
+
+  if (!parsed.ok) {
+    stderr(`Error: ${parsed.error}\n`);
+    stderr('Run "roll-parser --help" for usage.\n');
+    return 2;
+  }
+
+  const { args } = parsed;
+
+  if (args.showHelp) {
+    stdout(HELP_TEXT);
+    return 0;
+  }
+
+  if (args.showVersion) {
+    stdout(`${VERSION}\n`);
+    return 0;
+  }
+
+  if (args.notation == null) {
+    stderr('Error: No dice notation provided.\n');
+    stderr('Run "roll-parser --help" for usage.\n');
+    return 2;
+  }
+
+  try {
+    const options = args.seed != null ? { seed: args.seed } : {};
+    const result = roll(args.notation, options);
+    const output = formatResult(result, { json: args.json, verbose: args.verbose });
+    stdout(`${output}\n`);
+  } catch (error) {
+    if (isRollParserError(error)) {
+      stderr(`Error: ${error.message}\n`);
+      writeErrorContext(args.notation, error, stderr);
+      return 1;
+    }
+    throw error;
+  }
+
+  return 0;
+}