@arcforge/err 2.0.98

package/src/render.ts

@@ -0,0 +1,102 @@
+import type { AxonErrorSeverity, AxonErrorSource } from "./map"
+import type { AxonStackFrame } from "./stack"
+
+/**
+ * Rust-style call-site rendering — pure formatting over plain data. Every
+ * field here already lives on AxonError (map.ts's identity fields + the
+ * frames/snippets stack.ts captured at construction time) — nothing is
+ * parsed back out of a string, no disk access happens here. A future TUI
+ * component renders the exact same AxonErrorLike shape with its own layout;
+ * this module is one legitimate renderer of it, not the source of truth.
+ */
+
+export type AxonErrorLike = {
+    code: string
+    title: string
+    description: string
+    message: string
+    severity: AxonErrorSeverity
+    source: AxonErrorSource
+    context: Record<string, unknown> | undefined
+    frames: AxonStackFrame[]
+    cause?: unknown
+}
+
+/** One frame, Rust-style: file:line:col, then its captured source context with a caret. */
+export function renderFrame(frame: AxonStackFrame): string {
+    if (!frame.fileName || frame.lineNumber === null) {
+        return frame.functionName ? `at ${frame.functionName}` : "at <unknown>"
+    }
+
+    const location = `${frame.fileName}:${frame.lineNumber}:${frame.columnNumber ?? 0}`
+    const header = frame.functionName ? `at ${frame.functionName} (${location})` : `at ${location}`
+
+    const snippet = frame.source ? renderSnippet(frame.source, frame.lineNumber, frame.columnNumber) : null
+    return snippet ? `${header}\n${snippet}` : header
+}
+
+const RULE_WIDTH = 80
+
+/** The full renderable report: headline + description, a rule, then every frame and the cause chain. Blank line before and after the whole block. */
+export function renderError(error: AxonErrorLike): string {
+    const lines = [`Axon Error: ${error.title}`, error.description]
+
+    if (error.message && error.message !== error.title) {
+        lines.push("", error.message)
+    }
+
+    if (error.context && Object.keys(error.context).length > 0) {
+        lines.push("", "Context:", indent(renderContext(error.context)))
+    }
+
+    lines.push("─".repeat(RULE_WIDTH), ...error.frames.map(renderFrame))
+
+    if (error.cause !== undefined) {
+        lines.push("", "Caused by:", indent(causeMessage(error.cause)))
+    }
+
+    return ["", lines.join("\n"), ""].join("\n")
+}
+
+function renderContext(context: Record<string, unknown>): string {
+    return Object.entries(context)
+        .map(([key, value]) => `${key}: ${typeof value === "string" ? value : safeStringify(value)}`)
+        .join("\n")
+}
+
+/** JSON.stringify throws on circular structures — context is caller-supplied and not guaranteed serializable, so rendering it must never itself throw. */
+function safeStringify(value: unknown): string {
+    try {
+        return JSON.stringify(value)
+    } catch {
+        return String(value)
+    }
+}
+
+function causeMessage(cause: unknown): string {
+    return cause instanceof Error ? (cause.stack ?? cause.message) : String(cause)
+}
+
+function indent(text: string): string {
+    return text.split("\n").map(line => `  ${line}`).join("\n")
+}
+
+/** Gutter-numbered source lines with a caret under the reported column — all from already-captured data, no disk read. */
+function renderSnippet(source: AxonStackFrame["source"], lineNumber: number, columnNumber: number | null): string | null {
+    if (!source || source.length === 0) return null
+
+    const gutterWidth = String(source[source.length - 1]!.lineNumber).length
+
+    const rendered: string[] = []
+    for (const line of source) {
+        const num = String(line.lineNumber).padStart(gutterWidth, " ")
+        const marker = line.lineNumber === lineNumber ? ">" : " "
+        rendered.push(`  ${marker} ${num} | ${line.text}`)
+        if (line.lineNumber === lineNumber && columnNumber !== null) {
+            const caretPad = " ".repeat(gutterWidth + 6 + Math.max(0, columnNumber - 1))
+            rendered.push(`${caretPad}^`)
+        }
+    }
+
+    return rendered.join("\n")
+}

package/src/sink.ts

@@ -0,0 +1,37 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { AxonError } from "./err"
+
+/**
+ * Error attribution is a SCOPE, not a global. A process may host several
+ * Axon() runtimes at once, each with its own session log — a module-global
+ * sink (the old design) meant every error landed in whichever session
+ * registered last, silently misattributing instance A's failures to
+ * instance B's durable record.
+ *
+ * Instead, each runtime establishes its sink over its own well-defined
+ * entry points (Axon() construction, each kernel wake, reload) via
+ * AsyncLocalStorage: errScope.run(sink, fn). Every err() constructed
+ * anywhere downstream of that call — through awaits, promise chains,
+ * nested calls — reaches THAT runtime's session and no other.
+ *
+ * An err() constructed outside any scope (CLI tooling, tests, a callback
+ * scheduled outside a runtime's flow) reaches no sink: the error still
+ * throws and propagates to its catcher, which owns visibility at host
+ * level. Losing telemetry there is visible and fixable; misattribution
+ * would be a lie in the durable record — this fails in the right direction.
+ */
+export type AxonErrorSink = (error: AxonError) => void
+
+const storage = new AsyncLocalStorage<AxonErrorSink>()
+
+export const errScope = {
+    /** Run fn with every err() constructed downstream delivered to sink. Scopes nest — the innermost wins. */
+    run<T>(sink: AxonErrorSink, fn: () => T): T {
+        return storage.run(sink, fn)
+    },
+}
+
+/** err()'s delivery call — the current scope's sink, or nothing (see module doc). */
+export function emitError(error: AxonError): void {
+    storage.getStore()?.(error)
+}

package/src/stack.ts

@@ -0,0 +1,119 @@
+import { readFileSync } from "node:fs"
+
+/**
+ * Stack capture — one structured frame per call site, not an opaque string.
+ * Bun/V8 already resolve real .ts file+line+column with no source-map step
+ * (confirmed: running a .ts file directly reports its own source
+ * coordinates).
+ *
+ * The source snippet is captured HERE, at construction time, not read from
+ * disk later at render time. A TUI (or any renderer) replaying an AxonError
+ * from the session log may be on a different machine, after the file
+ * changed, or looking at a deployed bundle with no source on disk at all —
+ * the snippet has to already be data on the frame, or it's gone forever.
+ * render() only ever formats what's already here.
+ */
+
+// AxonSourceLine / AxonStackFrame are the wire contract — they live in
+// @arcforge/types and are re-exported here so err's internals and existing
+// importers resolve them from the same place.
+export type { AxonSourceLine, AxonStackFrame } from "@arcforge/types"
+import type { AxonSourceLine, AxonStackFrame } from "@arcforge/types"
+
+const FRAME_PATTERN_NAMED = /at\s+(.*?)\s+\((.*?):(\d+):(\d+)\)/
+const FRAME_PATTERN_BARE = /at\s+(.*?):(\d+):(\d+)/
+
+/** Noise no caller ever wants rendered — framework internals, not their code. */
+const IGNORED_PATH_SEGMENTS = ["node_modules", "native:", "internal", "bun:"]
+
+const CONTEXT_LINES = 2
+
+/**
+ * Capture the stack at the current call site, skipping `skipFrames` of it
+ * (use 1 to drop captureStack's own frame, 2 to also drop err()'s).
+ */
+export function captureStack(skipFrames: number = 1): AxonStackFrame[] {
+    const raw = new Error().stack
+    if (!raw) return []
+
+    const lines = raw.split("\n").slice(1 + skipFrames) // drop the "Error" header line + requested frames
+    return lines
+        .map(parseLine)
+        .filter(isRealFrame)
+        .map(withSource)
+}
+
+/**
+ * Parse an ALREADY-CAPTURED stack string (an unknown catch value's own
+ * `.stack`, not ours) into structured frames — same real-frame filtering
+ * and source-snippet capture as captureStack(), just over foreign text
+ * instead of `new Error().stack`. This is how a wrapped cause's own throw
+ * site becomes renderable: err()'s own frames point at the catch
+ * boundary that called err(), never at the user code that actually threw.
+ */
+export function parseStack(raw: string): AxonStackFrame[] {
+    return raw
+        .split("\n")
+        .slice(1) // drop the "Error: message" header line
+        .map(parseLine)
+        .filter(isRealFrame)
+        .map(withSource)
+}
+
+/** The first non-framework frame in a foreign stack — the user's own throw site, best-effort. Null when the stack has no such frame (e.g. a bare string throw has no stack at all). */
+export function firstRealFrame(raw: string | undefined): AxonStackFrame | null {
+    if (!raw) return null
+    return parseStack(raw)[0] ?? null
+}
+
+function parseLine(line: string): Omit<AxonStackFrame, "source"> {
+    const named = line.match(FRAME_PATTERN_NAMED)
+    if (named) {
+        const [, fn, file, ln, col] = named
+        return { functionName: fn ?? null, fileName: file ?? null, lineNumber: numberOr(ln), columnNumber: numberOr(col) }
+    }
+    const bare = line.match(FRAME_PATTERN_BARE)
+    if (bare) {
+        const [, file, ln, col] = bare
+        return { functionName: null, fileName: file ?? null, lineNumber: numberOr(ln), columnNumber: numberOr(col) }
+    }
+    return { functionName: null, fileName: null, lineNumber: null, columnNumber: null }
+}
+
+function numberOr(value: string | undefined): number | null {
+    if (value === undefined) return null
+    const n = parseInt(value, 10)
+    return Number.isNaN(n) ? null : n
+}
+
+function isRealFrame(frame: Omit<AxonStackFrame, "source">): boolean {
+    if (!frame.fileName) return false
+    return !IGNORED_PATH_SEGMENTS.some(segment => frame.fileName!.includes(segment))
+}
+
+function withSource(frame: Omit<AxonStackFrame, "source">): AxonStackFrame {
+    return { ...frame, source: readSourceWindow(frame.fileName, frame.lineNumber) }
+}
+
+/** `CONTEXT_LINES` of real source ± the reported line, captured as plain data — no disk access after this point. */
+function readSourceWindow(fileName: string | null, lineNumber: number | null): AxonSourceLine[] | null {
+    if (!fileName || lineNumber === null) return null
+
+    let text: string
+    try {
+        text = readFileSync(fileName, "utf-8")
+    } catch {
+        return null // source not reachable (deployed bundle, deleted file) — the header alone is still useful
+    }
+
+    const lines = text.split("\n")
+    const targetIdx = lineNumber - 1
+    if (targetIdx < 0 || targetIdx >= lines.length) return null
+
+    const from = Math.max(0, targetIdx - CONTEXT_LINES)
+    const to = Math.min(lines.length - 1, targetIdx + CONTEXT_LINES)
+
+    const window: AxonSourceLine[] = []
+    for (let i = from; i <= to; i++) window.push({ lineNumber: i + 1, text: lines[i] ?? "" })
+    return window
+}