roll-parser 3.3.0 → 3.4.0

package/src/cli/main.ts

@@ -8,10 +8,15 @@
  * @module cli/main
  */
 
-import { getErrorSpan, isRollParserError } from '../errors.js';
+import {
+  type ErrorSpan,
+  getErrorSpan,
+  isRollParserError,
+  type RollParserErrorCode,
+} from '../errors.js';
 import { VERSION } from '../index.js';
 import { roll } from '../roll.js';
-import { parseArgs } from './args.js';
+import { isKnownOption, parseArgs } from './args.js';
 import { formatResult } from './format.js';
 
 const HELP_TEXT = `roll-parser v${VERSION}
@@ -24,12 +29,23 @@ Options:
   -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
+  --               Notation that looks like an option — put options before it
 
 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.
+  Emits the complete result, including the structured "parts" tree, plus the
+  "seed" that produced it and the "version" that fixes the seed-to-dice
+  mapping — rerun with --seed <seed> on the same major to replay the roll.
+  When --seed is omitted the CLI mints one. The "degree" field
+  (DegreeOfSuccess) serializes as a number: 0 critical failure, 1 failure,
+  2 success, 3 critical success.
+
+JSON errors:
+  Every diagnostic is one JSON line on stderr:
+  {"error":{"message":...,"code":...,"span":{"start":N}},...}. A roll error
+  adds the "notation" and "seed" that produced it, so a failure replays like
+  a result does; "code" and "span" are absent when the failure carries
+  neither. Usage errors are covered too, but only where --json still reads as
+  the flag: it is a seed value in --seed --json, and notation after --.
 
 Exit codes:
   0  Success
@@ -41,9 +57,12 @@ Examples:
   roll-parser 4d6kh3 --verbose
   roll-parser 4d6dl1 --seed "character-str"
   roll-parser "1d20+7 vs 25" --json
-  roll-parser -- -1d6+3
+  roll-parser -1d6+3
 `;
 
+// The build sets `types: []`, so no ambient runtime globals are declared.
+declare const crypto: { randomUUID(): string };
+
 /** Sink for one stream's worth of CLI output. */
 export type WriteFn = (text: string) => void;
 
@@ -74,26 +93,73 @@ export function writeErrorContext(notation: string, error: unknown, write: Write
   write(`  ${' '.repeat(column)}^\n`);
 }
 
+/**
+ * Names the ordering rule when `--` swallowed an option. Gated on `terminated`,
+ * never on `argv` holding a `--`: `--seed --` makes that `--` a seed value, so a
+ * textual scan would name a terminator that never ran.
+ */
+function writeOptionHint(terminated: boolean, notation: string, write: WriteFn): void {
+  if (terminated && notation.split(' ').some(isKnownOption)) {
+    write('Hint: options must come before "--"\n');
+  }
+}
+
+/** The `error` member of the `--json` failure record. */
+type JsonErrorBody = {
+  message: string;
+  code?: RollParserErrorCode;
+  span?: ErrorSpan | undefined;
+};
+
+/**
+ * What the failure record needs to replay a roll that got as far as the
+ * dice. A usage error passes no context — it never reached the dice, so
+ * there is no roll to reproduce.
+ */
+type RollContext = {
+  notation: string;
+  seed: string;
+};
+
+/**
+ * Writes one failure record as compact JSON. `JSON.stringify` drops the
+ * absent members, so a lexer error carries no `end` and a usage error carries
+ * neither `code` nor `span` — the key is missing rather than null.
+ */
+function writeJsonError(write: WriteFn, error: JsonErrorBody, context?: RollContext): void {
+  write(`${JSON.stringify({ error, ...context, version: VERSION })}\n`);
+}
+
+/** Reports a usage error and returns the exit code for one. */
+function failUsage(stderr: WriteFn, message: string, json: boolean): number {
+  if (json) {
+    writeJsonError(stderr, { message });
+  } else {
+    stderr(`Error: ${message}\n`);
+    stderr('Run "roll-parser --help" for usage.\n');
+  }
+
+  return 2;
+}
+
 /**
  * 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.
+ * `--json` swaps the success payload on stdout and every diagnostic on
+ * stderr, usage errors included. Exit codes are identical either way, so
+ * scripts can still branch on the code before reading a stream.
  */
 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;
+    return failUsage(stderr, parsed.error, parsed.json);
   }
 
-  const { args } = parsed;
+  const { args, terminated } = parsed;
 
   if (args.showHelp) {
     stdout(HELP_TEXT);
@@ -106,20 +172,29 @@ export function main(env: CliEnv): number {
   }
 
   if (args.notation == null) {
-    stderr('Error: No dice notation provided.\n');
-    stderr('Run "roll-parser --help" for usage.\n');
-    return 2;
+    return failUsage(stderr, 'No dice notation provided.', args.json);
   }
 
+  // `SeededRNG`'s auto-seed is unreachable, so mint one that can be echoed back.
+  const seed = args.seed ?? crypto.randomUUID();
+
   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 });
+    const result = roll(args.notation, { seed });
+    const output = formatResult(result, { json: args.json, verbose: args.verbose, seed });
     stdout(`${output}\n`);
   } catch (error) {
     if (isRollParserError(error)) {
-      stderr(`Error: ${error.message}\n`);
-      writeErrorContext(args.notation, error, stderr);
+      if (args.json) {
+        writeJsonError(
+          stderr,
+          { message: error.message, code: error.code, span: getErrorSpan(error) },
+          { notation: args.notation, seed },
+        );
+      } else {
+        stderr(`Error: ${error.message}\n`);
+        writeErrorContext(args.notation, error, stderr);
+        writeOptionHint(terminated, args.notation, stderr);
+      }
       return 1;
     }
     throw error;