roll-parser 2.3.2 → 3.0.0-beta.0

package/package.json

@@ -1,18 +1,41 @@
 {
   "name": "roll-parser",
-  "version": "2.3.2",
-  "description": "Parser for classic (2d6+1), simple (2 6 1), and WoD (4d10!>6f1) dice rolls.",
-  "main": "index.js",
-  "bin": "bin/roll-parser.js",
+  "version": "3.0.0-beta.0",
+  "description": "High-performance dice notation parser for tabletop RPGs. TypeScript-first, Bun-optimized.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "roll-parser": "./dist/cli.js"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "!src/**/*.test.ts"
+  ],
   "keywords": [
     "parser",
     "dice",
     "roll",
     "rpg",
     "dnd",
-    "wod",
-    "random",
-    "d20"
+    "d20",
+    "pratt-parser",
+    "typescript",
+    "bun"
   ],
   "homepage": "https://github.com/edloidas/roll-parser#readme",
   "bugs": {
@@ -20,50 +43,50 @@
   },
   "license": "MIT",
   "author": "Mikita Taukachou <edloidas@gmail.com> (https://edloidas.com)",
-  "files": [
-    "index.js",
-    "bin",
-    "dist",
-    "src"
-  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/edloidas/roll-parser.git"
   },
-  "scripts": {
-    "test": "jest",
-    "cover": "jest --coverage",
-    "report": "node_modules/.bin/jest --coverage && cat coverage/lcov.info | node_modules/coveralls/bin/coveralls.js",
-    "fix": "eslint --fix .",
-    "api": "rimraf api/ && jsdoc -c .jsdocrc",
-    "clean": "rimraf dist/*",
-    "build:bundle": "browserify index.js --debug --standalone rollParser -o dist/roll-parser.js",
-    "build:minify": "babili dist/roll-parser.js --out-file dist/roll-parser.min.js",
-    "build": "npm run build:bundle && npm run build:minify",
-    "prepush": "npm test",
-    "prepublishOnly": "npm run fix && npm test && npm run clean && npm run build"
+  "publishConfig": {
+    "access": "public"
   },
-  "dependencies": {
-    "minimist": "^1.2.0"
+  "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",
+    "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",
+    "check:package": "attw --pack . --profile esm-only && publint",
+    "bench": "bun run bench/roll.bench.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",
+    "prepublishOnly": "bun run release:dry"
   },
   "devDependencies": {
-    "babel-core": "^6.24.1",
-    "babel-preset-babili": "^0.1.2",
-    "babili": "^0.1.2",
-    "browserify": "^14.4.0",
-    "coveralls": "^2.13.1",
-    "docdash": "^0.4.0",
-    "eslint": "^3.19.0",
-    "eslint-config-airbnb-base": "^11.2.0",
-    "eslint-plugin-import": "^2.3.0",
-    "husky": "^0.13.4",
-    "istanbul": "^0.4.5",
-    "jest": "^20.0.4",
-    "jsdoc": "^3.4.3",
-    "rimraf": "^2.6.1"
+    "@arethetypeswrong/cli": "^0.18.4",
+    "@biomejs/biome": "^2.4.9",
+    "@types/bun": "^1.3.0",
+    "fast-check": "^4.6.0",
+    "mitata": "^1.0.34",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.2"
   },
   "engines": {
-    "node": ">= 6.0.0",
-    "npm": ">= 3.8.6"
+    "node": ">= 22.0.0"
   }
 }

package/src/cli/args.ts

@@ -0,0 +1,73 @@
+/**
+ * CLI argument parser.
+ *
+ * Pure function that parses process.argv-style string arrays into typed options.
+ *
+ * @module cli/args
+ */
+
+/**
+ * Parsed CLI arguments.
+ */
+export type CliArgs = {
+  notation: string | undefined;
+  verbose: boolean;
+  seed: string | undefined;
+  showHelp: boolean;
+  showVersion: boolean;
+};
+
+/**
+ * Result of parsing CLI arguments — either success or a usage error.
+ */
+export type ParseArgsResult = { ok: true; args: CliArgs } | { ok: false; error: string };
+
+/**
+ * Parses a raw argument array into typed CLI options.
+ *
+ * @param argv - Arguments to parse (typically `process.argv.slice(2)`)
+ * @returns Parsed result or an error message for usage errors
+ */
+export function parseArgs(argv: string[]): ParseArgsResult {
+  let verbose = 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;
+    } else if (arg === '--verbose' || arg === '-v') {
+      verbose = true;
+    } else if (arg === '--seed') {
+      const next = argv[i + 1];
+      if (next === undefined || (next.startsWith('-') && !/^-\d/.test(next))) {
+        return { ok: false, error: 'Missing value for --seed' };
+      }
+      seed = next;
+      i++;
+    } else if (arg.startsWith('--seed=')) {
+      const value = arg.slice('--seed='.length);
+      if (value === '') {
+        return { ok: false, error: 'Missing value for --seed' };
+      }
+      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
+      return { ok: false, error: `Unknown option: ${arg}` };
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  const notation = positional.length > 0 ? positional.join(' ') : undefined;
+
+  return { ok: true, args: { notation, verbose, seed, showHelp, showVersion } };
+}

package/src/cli/format.ts

@@ -0,0 +1,49 @@
+/**
+ * CLI output formatting.
+ *
+ * Transforms RollResult into terminal-appropriate strings.
+ *
+ * @module cli/format
+ */
+
+import type { RollResult } from '../types.js';
+
+/**
+ * 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.
+ *
+ * @param result - The roll result to format
+ * @param verbose - Whether to show the detailed breakdown
+ * @returns Formatted string for terminal output
+ */
+export function formatResult(result: RollResult, verbose: boolean): string {
+  if (!verbose) {
+    return String(result.total);
+  }
+
+  return formatRendered(result.rendered);
+}
+
+/**
+ * Converts markdown-style dice markers to terminal-friendly forms.
+ *
+ * The evaluator uses markdown syntax in the rendered field:
+ *   `~~value~~` — dropped dice or dropped group sub-rolls
+ *   `**value**` — dice counted as success
+ *   `__value__` — dice counted as failure
+ *
+ * For plain terminals these become `(value)`, `[value]`, and `{value}` so
+ * the per-die classification stays visible without any markup dependency.
+ * Dropped spans can wrap a whole sub-roll (e.g. `~~1d8[2]~~` from
+ * `{1d8, 1d10}kh1`), so the strikethrough pattern accepts any tilde-free
+ * content, not just a single number. The evaluator never nests `~~`
+ * (see `stripInnerMarkers`), so the tilde-free span match is safe.
+ */
+function formatRendered(rendered: string): string {
+  return rendered
+    .replace(/\*\*(-?\d+)\*\*/g, '[$1]')
+    .replace(/__(-?\d+)__/g, '{$1}')
+    .replace(/~~([^~]+)~~/g, '($1)');
+}

package/src/cli/index.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for roll-parser.
+ *
+ * @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();

package/src/errors.ts

@@ -0,0 +1,90 @@
+/**
+ * Common error base class and error codes for roll-parser.
+ *
+ * @module errors
+ */
+
+/**
+ * All known roll-parser error codes. Single source of truth — the
+ * `RollParserErrorCode` type and the runtime `VALID_CODES` set are
+ * both derived from this array.
+ *
+ * Lexer: `UNEXPECTED_CHARACTER`, `UNEXPECTED_IDENTIFIER`
+ * Parser: `UNEXPECTED_TOKEN`, `UNEXPECTED_END`, `EXPECTED_TOKEN`,
+ *   `INVALID_MODIFIER_TARGET`, `INVALID_EXPLODE_TARGET`, `INVALID_REROLL_TARGET`,
+ *   `INVALID_SUCCESS_COUNT_TARGET`, `INVALID_SORT_TARGET`,
+ *   `INVALID_CRIT_THRESHOLD_TARGET`, `NESTED_VERSUS`, `INVALID_FUNCTION_ARITY`,
+ *   `AMBIGUOUS_DICE_CHAIN`, `MAX_DEPTH_EXCEEDED`
+ * Evaluator: `INVALID_DICE_COUNT`, `INVALID_DICE_SIDES`, `DICE_LIMIT_EXCEEDED`,
+ *   `DIVISION_BY_ZERO`, `MODULO_BY_ZERO`, `UNKNOWN_OPERATOR`, `UNKNOWN_NODE_TYPE`,
+ *   `INVALID_MODIFIER_COUNT`, `EXPLODE_LIMIT_EXCEEDED`, `REROLL_LIMIT_EXCEEDED`,
+ *   `INVALID_THRESHOLD`, `NESTED_VERSUS`, `UNKNOWN_FUNCTION`, `UNDEFINED_VARIABLE`,
+ *   `INVALID_VARIABLE_VALUE`, `NON_FINITE_RESULT`
+ */
+const ROLL_PARSER_ERROR_CODES = [
+  'UNEXPECTED_CHARACTER',
+  'UNEXPECTED_IDENTIFIER',
+  'UNEXPECTED_TOKEN',
+  'UNEXPECTED_END',
+  'EXPECTED_TOKEN',
+  'INVALID_DICE_COUNT',
+  'INVALID_DICE_SIDES',
+  'DICE_LIMIT_EXCEEDED',
+  'DIVISION_BY_ZERO',
+  'MODULO_BY_ZERO',
+  'UNKNOWN_OPERATOR',
+  'UNKNOWN_NODE_TYPE',
+  'INVALID_MODIFIER_COUNT',
+  'INVALID_MODIFIER_TARGET',
+  'EXPLODE_LIMIT_EXCEEDED',
+  'INVALID_EXPLODE_TARGET',
+  'REROLL_LIMIT_EXCEEDED',
+  'INVALID_REROLL_TARGET',
+  'INVALID_SUCCESS_COUNT_TARGET',
+  'INVALID_SORT_TARGET',
+  'INVALID_CRIT_THRESHOLD_TARGET',
+  'INVALID_THRESHOLD',
+  'NESTED_VERSUS',
+  'INVALID_FUNCTION_ARITY',
+  'UNKNOWN_FUNCTION',
+  'UNDEFINED_VARIABLE',
+  'INVALID_VARIABLE_VALUE',
+  'AMBIGUOUS_DICE_CHAIN',
+  'MAX_DEPTH_EXCEEDED',
+  'NON_FINITE_RESULT',
+] as const;
+
+export type RollParserErrorCode = (typeof ROLL_PARSER_ERROR_CODES)[number];
+
+/**
+ * Base error class for all roll-parser errors.
+ *
+ * Provides a typed `code` field for programmatic error handling.
+ * All library errors (`LexerError`, `ParseError`, `EvaluatorError`)
+ * extend this class.
+ */
+export class RollParserError extends Error {
+  readonly code: RollParserErrorCode;
+
+  constructor(message: string, code: RollParserErrorCode) {
+    super(message);
+    this.name = 'RollParserError';
+    this.code = code;
+  }
+}
+
+const VALID_CODES: Set<string> = new Set<string>(ROLL_PARSER_ERROR_CODES);
+
+/**
+ * Type guard for roll-parser errors. Checks `instanceof` first, then
+ * falls back to duck-typing for cross-realm safety.
+ */
+export function isRollParserError(value: unknown): value is RollParserError {
+  if (value instanceof RollParserError) return true;
+  return (
+    value instanceof Error &&
+    'code' in value &&
+    typeof (value as RollParserError).code === 'string' &&
+    VALID_CODES.has((value as RollParserError).code)
+  );
+}