@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.3

package/dist/fatal.js

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * The CLI's top-level catch handler, `bin/m3l-groundwork.mjs`'s last line of
+ * defence: whatever was thrown, and whatever fails while reporting it, the
+ * process ends with an exit code set and never with an uncaught throw.
+ */
+import { escapeControls, formatFatalError } from "./format-error.js";
+/** Printed when neither the formatted report nor the raw stack could be printed on the raw channel. */
+const LAST_RESORT = "[unprintable error]";
+/**
+ * `error.stack` when readable, otherwise `String(error)`, control-escaped by
+ * {@link escapeControls} -- the fallback text when printing the formatted
+ * chain failed.
+ */
+function rawText(error) {
+    // Read `stack` once, and only off an object; a throwing getter or Proxy
+    // trap propagates to the caller's own fallback.
+    const stack = typeof error === "object" && error !== null && "stack" in error
+        ? error.stack
+        : undefined;
+    return escapeControls(String(stack ?? error));
+}
+/**
+ * Reports a fatal `error`: sets the exit code first -- 2 when
+ * `isUsageError(error)` says it is a usage error, 1 otherwise, including
+ * when `isUsageError` itself throws -- then prints the report through
+ * `io.print`. For a usage error the report is exactly
+ * `formatErrorChain(error)`. For any other failure it is
+ * `formatFatalError(error, { withName: true, withStack: debug })` (both in
+ * `./format-error.ts`): the same chain, its top line prefixed `<name>: `
+ * when `error` is an `Error` with a readable, non-blank `name` other than
+ * `Error` and a non-blank message (`TypeError: boom`), and, when `debug` is
+ * set, the stack frames appended as `formatFatalError` describes
+ * (control-escaped, header dropped, capped at its `MAX_STACK_LINES`). Only
+ * the top error's own stack is printed: a `cause`'s stack is deliberately
+ * omitted, since the chain already names every cause. If that print
+ * throws, the fallbacks never touch `io.print` again (it is the channel
+ * that just failed -- in the CLI, the one that paints colour), so `print`
+ * is called exactly once: `io.printRaw` prints the same report, so the
+ * cause chain (and any name prefix and stack) survives a failing `print`;
+ * if that throws, `io.printRaw` prints `String(error.stack ?? error)`,
+ * control-escaped the same way the chain is (`escapeControls` in
+ * `./format-error.ts`); if that throws, `io.printRaw` prints
+ * `[unprintable error]`; if even that throws, gives up silently, the exit
+ * code already set. Never throws. A `setExitCode` that throws is swallowed
+ * and not retried -- the report is still attempted -- but it is not
+ * otherwise handled: assigning Node's `process.exitCode` cannot throw, so
+ * the CLI never hits that case.
+ *
+ * @param error - The value the CLI's `main()` threw.
+ * @param io - Where the exit code and the report go: `print` for the
+ * formatted chain, `printRaw` -- a plain write with nothing in it that can
+ * fail the way `print` did -- for all three fallbacks.
+ * @param isUsageError - Whether `error` is a bad invocation rather than a
+ * runtime failure.
+ * @param debug - Append the top error's own stack (never a cause's) to a
+ * runtime failure's report (never to a usage error's); defaults to `false`.
+ * The CLI sets it when `M3L_DEBUG` is non-empty.
+ *
+ * @example
+ * ```ts
+ * import { CliUsageError, main } from "./main.js";
+ * import { handleFatal } from "./fatal.js";
+ *
+ * try {
+ *   main(process.argv.slice(2));
+ * } catch (error) {
+ *   handleFatal(
+ *     error,
+ *     {
+ *       setExitCode: (code) => {
+ *         process.exitCode = code;
+ *       },
+ *       print: (text) => {
+ *         console.error(text);
+ *       },
+ *       printRaw: (text) => {
+ *         console.error(text);
+ *       },
+ *     },
+ *     (e) => e instanceof CliUsageError,
+ *     (process.env["M3L_DEBUG"] ?? "") !== "",
+ *   );
+ * }
+ * ```
+ */
+export function handleFatal(error, io, isUsageError, debug = false) {
+    let code = 1;
+    try {
+        code = isUsageError(error) ? 2 : 1;
+    }
+    catch {
+        // A classifier that throws cannot vouch for a usage error: a runtime failure.
+    }
+    try {
+        io.setExitCode(code);
+    }
+    catch {
+        // Nothing else can record the code; still try to print the report below.
+    }
+    const runtime = code === 1;
+    const options = { withName: runtime, withStack: runtime && debug };
+    try {
+        io.print(formatFatalError(error, options));
+        return;
+    }
+    catch {
+        // Fall through to the same report, on the raw channel.
+    }
+    try {
+        io.printRaw(formatFatalError(error, options));
+        return;
+    }
+    catch {
+        // Fall through to the raw stack.
+    }
+    try {
+        io.printRaw(rawText(error));
+        return;
+    }
+    catch {
+        // Fall through to the fixed placeholder.
+    }
+    try {
+        io.printRaw(LAST_RESORT);
+    }
+    catch {
+        // stderr itself is unusable: the exit code set above is all that is left.
+    }
+}
+//# sourceMappingURL=fatal.js.map

package/dist/format-error.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Makes `text` safe to write to a terminal: every line break it contains
+ * (`\r\n`, `\n`, a lone `\r`, `\v`, `\f`, U+0085, U+2028, U+2029) becomes a
+ * plain `\n`, and every other C0 control except TAB (U+0000-U+001F except
+ * U+0009), DEL (U+007F) and every C1 control except NEL (U+0080-U+009F
+ * except U+0085) is replaced by the literal text `\xNN`, lowercase two-digit
+ * hex -- so an ESC renders as `\x1b` and cannot start an escape sequence.
+ * Every bidi embedding/override and isolate control (U+202A-U+202E,
+ * U+2066-U+2069) is replaced by the literal text `\uNNNN`, lowercase
+ * four-digit hex -- so an RLO renders as `\u202e` and cannot reorder what
+ * the terminal displays. TAB and every other character pass through
+ * unchanged.
+ *
+ * @example
+ * ```ts
+ * import { escapeControls } from "./format-error.js";
+ *
+ * escapeControls("bad\u001b[2J\rline two"); // "bad\\x1b[2J\nline two"
+ * escapeControls("bad\u202eexe.txt"); // "bad\\u202eexe.txt"
+ * ```
+ */
+export declare function escapeControls(text: string): string;
+/**
+ * Formats `error` as a multi-line string: its own message on the first line
+ * (any further line of it indented two spaces), then one
+ * `caused by: <message>` line per chained cause, indented two more spaces
+ * per depth; any further line of a cause's message is indented two spaces
+ * past its own `caused by:` line. Every such continuation line is marked
+ * `| ` after its indent (an empty one prints a bare `|`), so no continuation
+ * line can pass for a real `caused by:` line; the top message's first line
+ * is printed unmarked (but control-escaped, below). Messages split on
+ * `\r\n`, `\n`, a lone `\r`, `\v`, `\f`, U+0085, U+2028 or U+2029; trailing
+ * empty lines are dropped. Every line of every message -- the top message's
+ * first line, any cause at any depth, a non-`Error`'s `String(value)` -- is
+ * then control-escaped exactly as {@link escapeControls} describes (every C0
+ * control but TAB, DEL, every C1 control but NEL become `\xNN`; every bidi
+ * control in U+202A-U+202E and U+2066-U+2069 becomes `\uNNNN`), so no
+ * message can emit a terminal escape sequence. A top message that is empty
+ * or whitespace-only renders as the `Error`'s `name` instead (when that is
+ * a readable, non-blank string), otherwise as `(empty message)`, so the
+ * first line is never blank. An `AggregateError`'s `errors` are each listed
+ * as a `caused by:` line at the next depth (after its own `cause`, if any);
+ * an `errors` property that is not an array is ignored. At most 32 `errors`
+ * members are printed per parent; the rest collapse into one
+ * `... and N more` line at the children's indent. A `cause` never counts
+ * against that cap, so it is always printed.
+ *
+ * A message is an `Error`'s `message`, otherwise `String(value)`; it renders
+ * as `[unprintable value]` when stringifying throws, when it is a `Symbol`,
+ * when the `message`, `cause` or `errors` accessor itself throws, or when the
+ * value cannot even be classified (a Proxy whose `getPrototypeOf` trap
+ * throws, a revoked Proxy) -- such a value has no children.
+ *
+ * A cause is not printed again (its own causes still are, at the same
+ * indent) when its message is not empty or whitespace-only and either equals
+ * the nearest printed ancestor's message after `trim()` or is at least 8
+ * characters long and contained in it.
+ *
+ * An object (or function) that is its own ancestor -- a cause cycle -- is
+ * cut silently at the repeat; one already printed on another branch renders
+ * as `caused by: (see above)`. Primitives are never deduplicated. Every
+ * branch follows at most 32 links -- suppressed links count too -- and a
+ * parent whose children are cut there gets exactly one `...` line, at the
+ * cut point, with any sibling branches still printed after it. The walk is
+ * iterative and bounded, so the function always terminates and never
+ * throws, however long the chain.
+ *
+ * @example
+ * ```ts
+ * import { formatErrorChain } from "./format-error.js";
+ *
+ * const error = new Error("staging failed", { cause: new Error("ENOSPC") });
+ * formatErrorChain(error);
+ * // "staging failed\n  caused by: ENOSPC"
+ * ```
+ */
+export declare function formatErrorChain(error: unknown): string;
+/**
+ * Formats `error` for the CLI's fatal-error report: exactly
+ * {@link formatErrorChain}'s text, with two optional additions.
+ *
+ * - `withName`: when `error` is an `Error` whose `name` is a readable,
+ *   non-blank string other than the generic `Error`, and its message is not
+ *   blank, the top line is prefixed `<name>: ` (`TypeError: boom`), the
+ *   name control-escaped like a message and any line break in it rendered
+ *   as a literal `\n`. A blank message already renders as the name alone,
+ *   so it gets no prefix; `caused by:` lines never do.
+ * - `withStack`: when `error` is an `Error` whose `stack` (read once) is a
+ *   string, its lines are appended after the chain -- minus V8's
+ *   `Name: message` header, which repeats the top line. The header is
+ *   dropped by position: as many leading lines as `Name: message` spans
+ *   when the stack starts with exactly those lines (so a message line
+ *   shaped like an `at ` frame never reappears), otherwise every line
+ *   before the first `at ` frame. Each line is control-escaped like a
+ *   message, at most {@link MAX_STACK_LINES} of them, the rest collapsing
+ *   into one `... and N more` line. A missing, non-string or throwing
+ *   `stack` appends nothing.
+ *
+ * Never throws, like {@link formatErrorChain}.
+ *
+ * @example
+ * ```ts
+ * import { formatFatalError } from "./format-error.js";
+ *
+ * formatFatalError(new TypeError("bad input"), { withName: true, withStack: false });
+ * // "TypeError: bad input"
+ * ```
+ */
+export declare function formatFatalError(error: unknown, options: {
+    readonly withName: boolean;
+    readonly withStack: boolean;
+}): string;
+//# sourceMappingURL=format-error.d.ts.map