From e54b806d21b76153341864b7e2b86ed2ba9b5911 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Wed, 27 May 2026 09:26:37 -0400 Subject: [PATCH] feat(vm/errors): expose structured error data and fix nested prefix wrapping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `Lua.VM.ErrorFormatter` produces beautiful ANSI-colored multi-line output for terminal callers, but consumers rendering errors in non-terminal contexts (HTML, JSON-over-wire, structured logs) had two problems: 1. Errors that flowed through `Lua.RuntimeException.exception/1` more than once accumulated `"Lua runtime error: Lua runtime error: …"` chains because four of the five clauses unconditionally prepended the prefix. 2. The data inside the formatter (source context, call stack, suggestion) was only emitted as an ANSI-encoded string. Consumers had to parse the formatted text to recover anything structured. Changes: - `Lua.RuntimeException`: route the four "Lua runtime error:" clauses through a `prefix_message/1` guard that only prepends when the inner message does not already start with the prefix. `{:api_error, ...}` is unchanged (different prefix). - `Lua.VM.ErrorFormatter`: extract `build_source_context/2`, `build_call_stack/1`, and `build_suggestion/3` as pure-data helpers shared by the existing ANSI renderers and a new public `to_map/3`. Terminal output is byte-for-byte unchanged (locked by golden tests). - `Lua.VM.RuntimeError`, `Lua.VM.TypeError`, `Lua.VM.AssertionError`: add `to_map/2` that delegates to `ErrorFormatter.to_map/3` and returns a wire-safe map with no ANSI escapes in any string field. Pass `:source_code` to populate `source_context`. Tests cover the single-prefix invariant across all four clauses, the `to_map/2` shape and ANSI-free guarantee, and golden snapshots locking `ErrorFormatter.format/3` output. --- lib/lua/runtime_exception.ex | 15 ++- lib/lua/vm/assertion_error.ex | 23 +++- lib/lua/vm/error_formatter.ex | 201 +++++++++++++++++++--------- lib/lua/vm/runtime_error.ex | 23 +++- lib/lua/vm/type_error.ex | 25 +++- test/lua/runtime_exception_test.exs | 63 +++++++++ test/lua/vm/error_to_map_test.exs | 160 ++++++++++++++++++++++ 7 files changed, 433 insertions(+), 77 deletions(-) create mode 100644 test/lua/vm/error_to_map_test.exs diff --git a/lib/lua/runtime_exception.ex b/lib/lua/runtime_exception.ex index 467615b5..6f7aa75d 100644 --- a/lib/lua/runtime_exception.ex +++ b/lib/lua/runtime_exception.ex @@ -15,15 +15,15 @@ defmodule Lua.RuntimeException do """ alias Lua.Util + @runtime_prefix "Lua runtime error: " + defexception [:message, :original, :state, :line, :source, :call_stack] @impl true def exception({:lua_error, error, _state}) do - message = Util.format_error(error) - %__MODULE__{ original: error, - message: "Lua runtime error: #{message}" + message: prefix_message(Util.format_error(error)) } end @@ -39,12 +39,12 @@ defmodule Lua.RuntimeException do %__MODULE__{ original: list, state: nil, - message: "Lua runtime error: #{format_function(scope, function)} failed, #{message}" + message: prefix_message("#{format_function(scope, function)} failed, #{message}") } end def exception(error) when is_binary(error) do - %__MODULE__{message: "Lua runtime error: #{String.trim(error)}"} + %__MODULE__{message: prefix_message(String.trim(error))} end def exception(error) do @@ -62,13 +62,16 @@ defmodule Lua.RuntimeException do %__MODULE__{ original: error, - message: "Lua runtime error: #{message}", + message: prefix_message(message), line: line, source: source, call_stack: call_stack } end + defp prefix_message(@runtime_prefix <> _ = msg), do: msg + defp prefix_message(msg), do: @runtime_prefix <> msg + defp extract_context(error) when is_struct(error) do {Map.get(error, :line), Map.get(error, :source), Map.get(error, :call_stack)} end diff --git a/lib/lua/vm/assertion_error.ex b/lib/lua/vm/assertion_error.ex index e0e39e3e..4eecf04d 100644 --- a/lib/lua/vm/assertion_error.ex +++ b/lib/lua/vm/assertion_error.ex @@ -7,6 +7,8 @@ defmodule Lua.VM.AssertionError do `Lua.VM.Executor.current_position/0`. """ + alias Lua.VM.ErrorFormatter + defexception [:value, :source, :message, :call_stack, :line] @impl true @@ -28,16 +30,31 @@ defmodule Lua.VM.AssertionError do } end - defp format_message(value, source, line, call_stack) do - error_msg = "assertion failed: #{stringify(value)}" + @doc """ + Returns a wire-safe structured map for this error. See + `Lua.VM.ErrorFormatter.to_map/3` for the shape. + + Pass `:source_code` to populate `source_context`. + """ + def to_map(%__MODULE__{} = error, opts \\ []) do + ErrorFormatter.to_map(:assertion_error, raw_message(error.value), + source: error.source, + line: error.line, + call_stack: error.call_stack, + source_code: Keyword.get(opts, :source_code) + ) + end - Lua.VM.ErrorFormatter.format(:assertion_error, error_msg, + defp format_message(value, source, line, call_stack) do + ErrorFormatter.format(:assertion_error, raw_message(value), source: source, line: line, call_stack: call_stack ) end + defp raw_message(value), do: "assertion failed: #{stringify(value)}" + defp stringify(nil), do: "nil" defp stringify(v) when is_binary(v), do: v defp stringify(v), do: inspect(v) diff --git a/lib/lua/vm/error_formatter.ex b/lib/lua/vm/error_formatter.ex index 00cf8673..b187db79 100644 --- a/lib/lua/vm/error_formatter.ex +++ b/lib/lua/vm/error_formatter.ex @@ -1,17 +1,18 @@ defmodule Lua.VM.ErrorFormatter do @moduledoc """ - Beautiful error formatting for Lua runtime errors. - - Provides detailed error messages with: - - ANSI-colored error type headers - - Clear error messages - - Source context with line numbers and pointer - - Stack traces - - Suggestions for common mistakes + Error formatting for Lua runtime errors. + + Two entry points share the same underlying data: + + * `format/3` renders an ANSI-colored multi-line string for terminal output + (headers, source context with pointer, stack trace, suggestion). + * `to_map/3` returns a wire-safe structured map for non-terminal consumers + (HTML rendering, JSON payloads, structured logs). No ANSI escapes appear + in any string field. """ @doc """ - Formats a runtime error into a beautiful multi-line string. + Formats a runtime error into a multi-line ANSI-colored string. ## Options @@ -43,6 +44,54 @@ defmodule Lua.VM.ErrorFormatter do |> Enum.join("\n") end + @doc """ + Returns a wire-safe structured representation of an error. + + The shape: + + %{ + type: atom(), + message: String.t(), + source: String.t() | nil, + line: pos_integer() | nil, + call_stack: [%{source: String.t() | nil, line: pos_integer() | nil, name: String.t() | nil}], + source_context: %{ + lines: [%{number: pos_integer(), text: String.t(), highlight?: boolean()}], + pointer_column: pos_integer() | nil + } | nil, + suggestion: String.t() | nil, + error_kind: atom() | nil + } + + `source_context` is only populated when both `:source_code` and `:line` are + provided. `pointer_column` reflects the column where the `^` marker points; + the formatter does not currently track real column positions, so it is `1` + when a highlighted line is present and `nil` otherwise. + + ## Options + + Accepts the same options as `format/3`. + """ + def to_map(error_type, message, opts \\ []) do + source = Keyword.get(opts, :source) + line = Keyword.get(opts, :line) + call_stack = Keyword.get(opts, :call_stack, []) + source_code = Keyword.get(opts, :source_code) + error_kind = Keyword.get(opts, :error_kind) + value_type = Keyword.get(opts, :value_type) + + %{ + type: error_type, + message: message, + source: source, + line: line, + call_stack: build_call_stack(call_stack), + source_context: build_source_context(source_code, line), + suggestion: build_suggestion(error_type, error_kind, value_type), + error_kind: error_kind + } + end + defp format_header(:type_error) do IO.ANSI.red() <> IO.ANSI.bright() <> "Runtime Type Error" <> IO.ANSI.reset() end @@ -66,45 +115,61 @@ defmodule Lua.VM.ErrorFormatter do "\n #{message}" end - defp format_source_context(nil, _line), do: nil - defp format_source_context(_source_code, nil), do: nil + defp format_source_context(source_code, line) do + case build_source_context(source_code, line) do + nil -> nil + %{lines: lines} -> render_source_context(lines) + end + end + + defp render_source_context(lines) do + context_lines = + Enum.flat_map(lines, fn %{number: num, text: text, highlight?: highlight?} -> + line_str = format_line_number(num) <> " │ " <> text - defp format_source_context(source_code, line) when is_binary(source_code) do + if highlight? do + pointer_offset = String.length(format_line_number(num)) + 3 + + pointer = + String.duplicate(" ", pointer_offset) <> IO.ANSI.red() <> "^" <> IO.ANSI.reset() + + [ + "\n" <> IO.ANSI.red() <> line_str <> IO.ANSI.reset(), + pointer + ] + else + ["\n" <> IO.ANSI.faint() <> line_str <> IO.ANSI.reset()] + end + end) + + "\n" <> Enum.join(context_lines) + end + + defp build_source_context(nil, _line), do: nil + defp build_source_context(_source_code, nil), do: nil + + defp build_source_context(source_code, line) when is_binary(source_code) and is_integer(line) do lines = String.split(source_code, "\n") + total = length(lines) - if line > 0 and line <= length(lines) do - # Show 2 lines before and after + if line > 0 and line <= total do start_line = max(1, line - 2) - end_line = min(length(lines), line + 2) + end_line = min(total, line + 2) - context_lines = + rendered_lines = lines |> Enum.slice((start_line - 1)..(end_line - 1)) |> Enum.with_index(start_line) - |> Enum.flat_map(fn {line_text, num} -> - line_str = format_line_number(num) <> " │ " <> line_text - - if num == line do - # Error line - add pointer - pointer_offset = String.length(format_line_number(num)) + 3 - - pointer = - String.duplicate(" ", pointer_offset) <> IO.ANSI.red() <> "^" <> IO.ANSI.reset() - - [ - "\n" <> IO.ANSI.red() <> line_str <> IO.ANSI.reset(), - pointer - ] - else - # Context line - ["\n" <> IO.ANSI.faint() <> line_str <> IO.ANSI.reset()] - end + |> Enum.map(fn {text, num} -> + %{number: num, text: text, highlight?: num == line} end) - "\n" <> Enum.join(context_lines) + %{lines: rendered_lines, pointer_column: 1} end end + defp build_source_context(_source_code, _line), do: nil + defp format_line_number(num) do num |> Integer.to_string() @@ -114,11 +179,26 @@ defmodule Lua.VM.ErrorFormatter do defp format_stack_trace([]), do: nil defp format_stack_trace(call_stack) when is_list(call_stack) do - frames = Enum.map_join(call_stack, "\n", &format_frame/1) + frames = + call_stack + |> build_call_stack() + |> Enum.map_join("\n", &format_frame/1) "\n\n" <> IO.ANSI.cyan() <> "Stack trace:" <> IO.ANSI.reset() <> "\n" <> frames end + defp build_call_stack(call_stack) when is_list(call_stack) do + Enum.map(call_stack, fn frame -> + %{ + source: Map.get(frame, :source), + line: Map.get(frame, :line), + name: Map.get(frame, :name) + } + end) + end + + defp build_call_stack(_), do: [] + defp format_frame(%{source: source, line: line, name: name}) do location = " #{source || "-no-source-"}:#{line}:" @@ -131,41 +211,38 @@ defmodule Lua.VM.ErrorFormatter do location <> context end - defp format_suggestion(:type_error, error_kind, value_type) do - case error_kind do - :call_nil -> - suggestion( - "The value you're trying to call as a function is nil. Check that the function exists and is defined before this point." - ) - - :call_non_function -> - type_name = format_type_name(value_type) - - suggestion("You can only call function values. Check that you're calling a function, not a #{type_name}.") + defp format_suggestion(error_type, error_kind, value_type) do + case build_suggestion(error_type, error_kind, value_type) do + nil -> nil + text -> suggestion(text) + end + end - :index_non_table -> - type_name = format_type_name(value_type) + defp build_suggestion(:type_error, :call_nil, _value_type) do + "The value you're trying to call as a function is nil. Check that the function exists and is defined before this point." + end - suggestion("You can only index tables. Make sure the value you're indexing is a table, not a #{type_name}.") + defp build_suggestion(:type_error, :call_non_function, value_type) do + "You can only call function values. Check that you're calling a function, not a #{format_type_name(value_type)}." + end - :arithmetic_type_error -> - suggestion( - "Arithmetic operations require numbers. Make sure both operands are numbers or strings that can be converted to numbers." - ) + defp build_suggestion(:type_error, :index_non_table, value_type) do + "You can only index tables. Make sure the value you're indexing is a table, not a #{format_type_name(value_type)}." + end - :concatenate_type_error -> - suggestion("String concatenation (..) requires strings or numbers, not other types.") + defp build_suggestion(:type_error, :arithmetic_type_error, _value_type) do + "Arithmetic operations require numbers. Make sure both operands are numbers or strings that can be converted to numbers." + end - _ -> - nil - end + defp build_suggestion(:type_error, :concatenate_type_error, _value_type) do + "String concatenation (..) requires strings or numbers, not other types." end - defp format_suggestion(:assertion_error, _error_kind, _value_type) do - suggestion("The assertion condition evaluated to false or nil. Check your logic.") + defp build_suggestion(:assertion_error, _error_kind, _value_type) do + "The assertion condition evaluated to false or nil. Check your logic." end - defp format_suggestion(_, _, _), do: nil + defp build_suggestion(_, _, _), do: nil defp suggestion(text) do "\n\n" <> IO.ANSI.cyan() <> "Suggestion:" <> IO.ANSI.reset() <> "\n " <> text diff --git a/lib/lua/vm/runtime_error.ex b/lib/lua/vm/runtime_error.ex index 3640acfe..3e466d91 100644 --- a/lib/lua/vm/runtime_error.ex +++ b/lib/lua/vm/runtime_error.ex @@ -13,6 +13,8 @@ defmodule Lua.VM.RuntimeError do attribution automatically. """ + alias Lua.VM.ErrorFormatter + defexception [:value, :source, :message, :call_stack, :line] @impl true @@ -34,16 +36,31 @@ defmodule Lua.VM.RuntimeError do } end - defp format_message(value, source, line, call_stack) do - error_msg = "runtime error: #{stringify(value)}" + @doc """ + Returns a wire-safe structured map for this error. See + `Lua.VM.ErrorFormatter.to_map/3` for the shape. + + Pass `:source_code` to populate `source_context`. + """ + def to_map(%__MODULE__{} = error, opts \\ []) do + ErrorFormatter.to_map(:runtime_error, raw_message(error.value), + source: error.source, + line: error.line, + call_stack: error.call_stack, + source_code: Keyword.get(opts, :source_code) + ) + end - Lua.VM.ErrorFormatter.format(:runtime_error, error_msg, + defp format_message(value, source, line, call_stack) do + ErrorFormatter.format(:runtime_error, raw_message(value), source: source, line: line, call_stack: call_stack ) end + defp raw_message(value), do: "runtime error: #{stringify(value)}" + defp stringify(nil), do: "nil" defp stringify(v) when is_binary(v), do: v defp stringify(v), do: inspect(v) diff --git a/lib/lua/vm/type_error.ex b/lib/lua/vm/type_error.ex index 4fab3053..0645669d 100644 --- a/lib/lua/vm/type_error.ex +++ b/lib/lua/vm/type_error.ex @@ -12,6 +12,8 @@ defmodule Lua.VM.TypeError do attribution automatically. """ + alias Lua.VM.ErrorFormatter + defexception [:value, :source, :message, :call_stack, :line, :error_kind, :value_type] @impl true @@ -40,10 +42,25 @@ defmodule Lua.VM.TypeError do } end - defp format_message(value, source, line, call_stack, error_kind, value_type) do - error_msg = stringify(value) + @doc """ + Returns a wire-safe structured map for this error. See + `Lua.VM.ErrorFormatter.to_map/3` for the shape. + + Pass `:source_code` to populate `source_context`. + """ + def to_map(%__MODULE__{} = error, opts \\ []) do + ErrorFormatter.to_map(:type_error, raw_message(error.value), + source: error.source, + line: error.line, + call_stack: error.call_stack, + error_kind: error.error_kind, + value_type: error.value_type, + source_code: Keyword.get(opts, :source_code) + ) + end - Lua.VM.ErrorFormatter.format(:type_error, error_msg, + defp format_message(value, source, line, call_stack, error_kind, value_type) do + ErrorFormatter.format(:type_error, raw_message(value), source: source, line: line, call_stack: call_stack, @@ -52,6 +69,8 @@ defmodule Lua.VM.TypeError do ) end + defp raw_message(value), do: stringify(value) + defp stringify(nil), do: "nil" defp stringify(v) when is_binary(v), do: v defp stringify(v), do: inspect(v) diff --git a/test/lua/runtime_exception_test.exs b/test/lua/runtime_exception_test.exs index 8c56f06a..e87a6132 100644 --- a/test/lua/runtime_exception_test.exs +++ b/test/lua/runtime_exception_test.exs @@ -433,6 +433,69 @@ defmodule Lua.RuntimeExceptionTest do end end + describe "single-prefix invariant" do + # Wrapping an already-prefixed message should not produce + # "Lua runtime error: Lua runtime error: ..." chains. + + test "binary clause does not double-prefix" do + exception = RuntimeException.exception("Lua runtime error: already prefixed") + + assert exception.message == "Lua runtime error: already prefixed" + end + + test "binary clause trims then guards" do + exception = RuntimeException.exception(" Lua runtime error: trimmed \n") + + assert exception.message == "Lua runtime error: trimmed" + end + + test "lua_error tuple clause does not double-prefix" do + exception = + RuntimeException.exception({:lua_error, "Lua runtime error: from inner error", State.new()}) + + assert exception.message == "Lua runtime error: from inner error" + end + + test "catch-all clause does not double-prefix when wrapping a VM exception" do + inner = + Lua.VM.RuntimeError.exception( + value: "boom", + source: "t.lua", + line: 3, + message: "Lua runtime error: boom" + ) + + exception = RuntimeException.exception(inner) + + assert exception.message == "Lua runtime error: boom" + end + + test "catch-all clause does not double-prefix when wrapping a built-in exception" do + inner = RuntimeError.exception("Lua runtime error: already wrapped") + + exception = RuntimeException.exception(inner) + + assert exception.message == "Lua runtime error: already wrapped" + end + + test "keyword list clause still prefixes (inner never starts with prefix)" do + exception = + RuntimeException.exception( + scope: ["m"], + function: "f", + message: "boom" + ) + + assert exception.message == "Lua runtime error: m.f() failed, boom" + end + + test "binary clause still prefixes plain messages" do + exception = RuntimeException.exception("plain message") + + assert exception.message == "Lua runtime error: plain message" + end + end + describe "stack trace pruning" do # The rescued Elixir stacktrace should not contain frames from the # VM, compiler, parser, or lexer internals — those are noise to a diff --git a/test/lua/vm/error_to_map_test.exs b/test/lua/vm/error_to_map_test.exs new file mode 100644 index 00000000..35c43699 --- /dev/null +++ b/test/lua/vm/error_to_map_test.exs @@ -0,0 +1,160 @@ +defmodule Lua.VM.ErrorToMapTest do + use ExUnit.Case, async: true + + alias Lua.VM.AssertionError, as: VMAssertionError + alias Lua.VM.ErrorFormatter + alias Lua.VM.RuntimeError, as: VMRuntimeError + alias Lua.VM.TypeError, as: VMTypeError + + @ansi_escape "\e[" + + describe "Lua.VM.RuntimeError.to_map/2" do + test "returns the full structured shape" do + error = + VMRuntimeError.exception( + value: "boom", + source: "t.lua", + line: 3, + call_stack: [%{source: "t.lua", line: 3, name: "fn1"}] + ) + + map = VMRuntimeError.to_map(error) + + assert map.type == :runtime_error + assert map.message == "runtime error: boom" + assert map.source == "t.lua" + assert map.line == 3 + assert map.call_stack == [%{source: "t.lua", line: 3, name: "fn1"}] + assert map.source_context == nil + assert map.suggestion == nil + assert map.error_kind == nil + end + + test "source_context is populated when source_code is passed" do + error = VMRuntimeError.exception(value: "boom", source: "t.lua", line: 2) + + map = VMRuntimeError.to_map(error, source_code: "a\nb\nc") + + assert %{lines: lines, pointer_column: 1} = map.source_context + assert length(lines) == 3 + assert Enum.at(lines, 0) == %{number: 1, text: "a", highlight?: false} + assert Enum.at(lines, 1) == %{number: 2, text: "b", highlight?: true} + assert Enum.at(lines, 2) == %{number: 3, text: "c", highlight?: false} + end + + test "no ANSI escape sequences appear in any string field" do + error = + VMRuntimeError.exception( + value: "boom", + source: "t.lua", + line: 2, + call_stack: [%{source: "t.lua", line: 2, name: "fn1"}] + ) + + map = VMRuntimeError.to_map(error, source_code: "a\nb\nc") + + refute String.contains?(map.message, @ansi_escape) + + for line <- map.source_context.lines do + refute String.contains?(line.text, @ansi_escape) + end + end + end + + describe "Lua.VM.TypeError.to_map/2" do + test "carries through :error_kind and :value_type, and emits a plain suggestion" do + error = + VMTypeError.exception( + value: "attempt to call a nil value", + source: "t.lua", + line: 4, + error_kind: :call_nil + ) + + map = VMTypeError.to_map(error) + + assert map.type == :type_error + assert map.error_kind == :call_nil + assert is_binary(map.suggestion) + refute String.contains?(map.suggestion, @ansi_escape) + assert map.message == "attempt to call a nil value" + end + + test "value_type informs suggestion text" do + error = + VMTypeError.exception( + value: "attempt to index a number value", + source: "t.lua", + line: 1, + error_kind: :index_non_table, + value_type: :number + ) + + map = VMTypeError.to_map(error) + + assert map.suggestion =~ "number" + refute String.contains?(map.suggestion, @ansi_escape) + end + end + + describe "Lua.VM.AssertionError.to_map/2" do + test "returns assertion suggestion without ANSI" do + error = VMAssertionError.exception(value: "expected true", source: "t.lua", line: 1) + + map = VMAssertionError.to_map(error) + + assert map.type == :assertion_error + assert map.message == "assertion failed: expected true" + assert is_binary(map.suggestion) + refute String.contains?(map.suggestion, @ansi_escape) + assert map.error_kind == nil + end + end + + describe "Lua.VM.ErrorFormatter.format/3 stability" do + # Golden snapshots locking the terminal output. If a refactor changes + # what terminal callers see, these fail loudly. + + test "type_error with source_code, stack, and suggestion" do + output = + ErrorFormatter.format(:type_error, "attempt to call a nil value", + source: "t.lua", + line: 2, + source_code: "local x\nx()\nreturn 0", + call_stack: [%{source: "t.lua", line: 2, name: nil}], + error_kind: :call_nil + ) + + expected = + "\e[31m\e[1mRuntime Type Error\e[0m\n\n at t.lua:2:\n\n attempt to call a nil value\n\n\n\e[2m 1 │ local x\e[0m\n\e[31m 2 │ x()\e[0m \e[31m^\e[0m\n\e[2m 3 │ return 0\e[0m\n\n\n\e[36mStack trace:\e[0m\n t.lua:2: in main chunk\n\n\n\e[36mSuggestion:\e[0m\n The value you're trying to call as a function is nil. Check that the function exists and is defined before this point." + + assert output == expected + end + + test "runtime_error with no source_code or suggestion" do + output = + ErrorFormatter.format(:runtime_error, "runtime error: boom", + source: "t.lua", + line: 1, + call_stack: [%{source: "t.lua", line: 1, name: "f"}] + ) + + expected = + "\e[31m\e[1mRuntime Error\e[0m\n\n at t.lua:1:\n\n runtime error: boom\n\n\n\e[36mStack trace:\e[0m\n t.lua:1: in function 'f'" + + assert output == expected + end + + test "assertion_error with empty stack still emits suggestion" do + output = ErrorFormatter.format(:assertion_error, "assertion failed: nope") + + expected = + "\e[31m\e[1mAssertion Failed\e[0m" <> + "\n\n assertion failed: nope" <> + "\n\n\n\e[36mSuggestion:\e[0m" <> + "\n The assertion condition evaluated to false or nil. Check your logic." + + assert output == expected + end + end +end