diff --git a/lib/lua/parser.ex b/lib/lua/parser.ex index 6b89b8e3..133a420c 100644 --- a/lib/lua/parser.ex +++ b/lib/lua/parser.ex @@ -35,22 +35,54 @@ defmodule Lua.Parser do """ @spec parse(String.t()) :: {:ok, Chunk.t()} | {:error, String.t()} def parse(code) when is_binary(code) do + case parse_to_error(code) do + {:ok, chunk} -> {:ok, chunk} + {:error, error} -> {:error, Error.format(error, code)} + end + end + + @doc """ + Parses Lua source code and returns structured errors. + + Unlike `parse/1`, which returns a pre-formatted display string, this + returns the `t:Lua.Parser.Error.t/0` structs directly so consumers can + render errors in their own UI (editors, LSPs, web frontends) without + scraping the formatted output. Use `Lua.Parser.Error.to_map/2` to obtain a + JSON-serializable shape. + + The error list always holds a single error today; the list shape leaves + room for multi-error recovery without a breaking change. + + ## Examples + + iex> {:ok, %Lua.AST.Chunk{}} = Lua.Parser.parse_structured("local x = 42") + + iex> {:error, [error]} = Lua.Parser.parse_structured("if x then") + iex> error.type + :unexpected_token + """ + @spec parse_structured(String.t()) :: {:ok, Chunk.t()} | {:error, [Error.t()]} + def parse_structured(code) when is_binary(code) do + case parse_to_error(code) do + {:ok, chunk} -> {:ok, chunk} + {:error, error} -> {:error, [error]} + end + end + + # Shared parse path producing a converted `Lua.Parser.Error` struct on + # failure. `parse/1` formats it; `parse_structured/1` returns it. Keeping + # both on this helper stops the display and structured paths from drifting. + @spec parse_to_error(String.t()) :: {:ok, Chunk.t()} | {:error, Error.t()} + defp parse_to_error(code) do case Lexer.tokenize(code) do {:ok, tokens} -> case parse_chunk(tokens) do - {:ok, chunk} -> - {:ok, chunk} - - {:error, reason} -> - error = convert_error(reason, code) - formatted = Error.format(error, code) - {:error, formatted} + {:ok, chunk} -> {:ok, chunk} + {:error, reason} -> {:error, convert_error(reason, code)} end {:error, reason} -> - error = convert_lexer_error(reason, code) - formatted = Error.format(error, code) - {:error, formatted} + {:error, convert_lexer_error(reason, code)} end end diff --git a/lib/lua/parser/error.ex b/lib/lua/parser/error.ex index 52b42ee0..ab17934b 100644 --- a/lib/lua/parser/error.ex +++ b/lib/lua/parser/error.ex @@ -31,6 +31,29 @@ defmodule Lua.Parser.Error do | :lexer_error | :multiple_errors + @type source_context :: %{ + lines: [%{number: pos_integer(), text: String.t(), highlight?: boolean()}], + pointer_column: pos_integer() + } + + @typedoc """ + Wire-safe representation produced by `to_map/2`. Mirrors the shape of + `Lua.VM.ErrorFormatter.to_map/3` so runtime and parse errors render + through one path. `source`, `call_stack`, and `error_kind` are constant + for parse errors (no file name, stack, or error kind) and exist only for + shape parity. + """ + @type wire_error :: %{ + type: error_type(), + message: String.t() | nil, + source: nil, + line: pos_integer() | nil, + call_stack: [], + source_context: source_context() | nil, + suggestion: String.t() | nil, + error_kind: nil + } + defstruct [ :type, :message, @@ -120,6 +143,88 @@ defmodule Lua.Parser.Error do new(:unexpected_end, message, position, suggestion: suggestion) end + @doc """ + Returns a wire-safe structured representation of a parse error. + + The shape is identical to `Lua.VM.ErrorFormatter.to_map/3`, so runtime and + parse errors can flow through a single renderer (HTML, JSON, structured + logs). No ANSI escapes appear in any string field, and leading/trailing + whitespace from the internal message/suggestion templates is trimmed. + + %{ + type: atom(), + message: String.t(), + source: String.t() | nil, + line: pos_integer() | nil, + call_stack: [], + source_context: %{ + lines: [%{number: pos_integer(), text: String.t(), highlight?: boolean()}], + pointer_column: pos_integer() + } | nil, + suggestion: String.t() | nil, + error_kind: nil + } + + Parse errors carry no call stack or error kind, so `call_stack` is always + `[]` and `error_kind` is always `nil`; they are present for shape parity. + `source` is `nil` because the parser does not track a file name. + + Pass the original source code as the second argument to populate + `source_context`. The `pointer_column` is taken from the error's real + column when a position is known, so the `^` marker lands on the offending + token instead of always pointing at column 1. + + iex> {:error, [error]} = Lua.Parser.parse_structured("if x then") + iex> map = Lua.Parser.Error.to_map(error, "if x then") + iex> {map.type, map.source_context.pointer_column} + {:unexpected_token, 10} + """ + @spec to_map(t(), String.t() | nil) :: wire_error() + def to_map(%__MODULE__{} = error, source_code \\ nil) do + %{ + type: error.type, + message: clean(error.message), + source: nil, + line: error.position && error.position.line, + call_stack: [], + source_context: build_source_context(source_code, error.position), + suggestion: clean(error.suggestion), + error_kind: nil + } + end + + defp clean(nil), do: nil + defp clean(text) when is_binary(text), do: String.trim(text) + + # Deliberately mirrors `Lua.VM.ErrorFormatter`'s private source-context + # windowing (same 2-before/2-after math) to keep the wire shapes in lockstep. + # Duplicated rather than shared so the parser stays decoupled from the VM; + # the parity test in error_to_map_test.exs guards against the two drifting. + defp build_source_context(nil, _position), do: nil + defp build_source_context(_source_code, nil), do: nil + + defp build_source_context(source_code, %{line: line} = position) when is_binary(source_code) and is_integer(line) do + lines = String.split(source_code, "\n") + total = length(lines) + + if line > 0 and line <= total do + start_line = max(1, line - 2) + end_line = min(total, line + 2) + + rendered_lines = + lines + |> Enum.slice((start_line - 1)..(end_line - 1)) + |> Enum.with_index(start_line) + |> Enum.map(fn {text, num} -> + %{number: num, text: text, highlight?: num == line} + end) + + %{lines: rendered_lines, pointer_column: position.column} + end + end + + defp build_source_context(_source_code, _position), do: nil + @doc """ Formats an error into a beautiful multi-line string with context. """ diff --git a/test/lua/parser/error_to_map_test.exs b/test/lua/parser/error_to_map_test.exs new file mode 100644 index 00000000..ba5ad570 --- /dev/null +++ b/test/lua/parser/error_to_map_test.exs @@ -0,0 +1,137 @@ +defmodule Lua.Parser.ErrorToMapTest do + use ExUnit.Case, async: true + + alias Lua.Parser + alias Lua.Parser.Error + alias Lua.VM.ErrorFormatter + + @ansi_escape "\e[" + + describe "to_map/1" do + test "returns the full structured shape with nil source_context when no code given" do + position = %{line: 3, column: 7, byte_offset: 20} + error = Error.new(:unexpected_token, "boom", position, suggestion: "try this") + + map = Error.to_map(error) + + assert map == %{ + type: :unexpected_token, + message: "boom", + source: nil, + line: 3, + call_stack: [], + source_context: nil, + suggestion: "try this", + error_kind: nil + } + end + + test "trims trailing newlines from message and suggestion" do + error = Error.new(:unexpected_end, "ran out\n", nil, suggestion: "add end\n") + + map = Error.to_map(error) + + assert map.message == "ran out" + assert map.suggestion == "add end" + end + + test "line and suggestion are nil when absent" do + error = Error.new(:invalid_syntax, "bad") + + map = Error.to_map(error) + + assert map.line == nil + assert map.suggestion == nil + assert map.source_context == nil + end + end + + describe "to_map/2 source_context" do + test "builds a 2-before/2-after window with the real pointer column" do + position = %{line: 3, column: 4, byte_offset: 0} + error = Error.new(:unexpected_token, "boom", position) + + map = Error.to_map(error, "a\nb\nc\nd\ne") + + assert %{lines: lines, pointer_column: 4} = map.source_context + + assert lines == [ + %{number: 1, text: "a", highlight?: false}, + %{number: 2, text: "b", highlight?: false}, + %{number: 3, text: "c", highlight?: true}, + %{number: 4, text: "d", highlight?: false}, + %{number: 5, text: "e", highlight?: false} + ] + end + + test "clamps the window at the start of the file" do + position = %{line: 1, column: 1, byte_offset: 0} + error = Error.new(:unexpected_token, "boom", position) + + map = Error.to_map(error, "a\nb\nc") + + assert Enum.map(map.source_context.lines, & &1.number) == [1, 2, 3] + assert hd(map.source_context.lines).highlight? + end + + test "source_context is nil when the line is out of range" do + position = %{line: 99, column: 1, byte_offset: 0} + error = Error.new(:unexpected_token, "boom", position) + + assert Error.to_map(error, "a\nb").source_context == nil + end + + test "pointer_column tracks the real column of a parser-produced error" do + code = "local x = 1 +" + {:error, [error]} = Parser.parse_structured(code) + + assert Error.to_map(error, code).source_context.pointer_column == error.position.column + assert error.position.column > 1 + end + end + + describe "wire-shape parity and safety" do + test "shares the same top-level keys as Lua.VM.ErrorFormatter.to_map/3" do + parse_keys = "x +" |> error!() |> Error.to_map("x +") |> Map.keys() |> Enum.sort() + + formatter_keys = + :type_error + |> ErrorFormatter.to_map("boom", source_code: "a\nb", line: 1) + |> Map.keys() + |> Enum.sort() + + assert parse_keys == formatter_keys + end + + test "source_context shape matches Lua.VM.ErrorFormatter.to_map/3 key-for-key" do + parse_context = "x +" |> error!() |> Error.to_map("x +") |> Map.fetch!(:source_context) + + formatter_context = + :type_error + |> ErrorFormatter.to_map("boom", source_code: "a\nb", line: 1) + |> Map.fetch!(:source_context) + + assert parse_context |> Map.keys() |> Enum.sort() == + formatter_context |> Map.keys() |> Enum.sort() + + assert parse_context.lines |> hd() |> Map.keys() |> Enum.sort() == + formatter_context.lines |> hd() |> Map.keys() |> Enum.sort() + end + + test "no ANSI escapes appear in any string field" do + map = "if x then" |> error!() |> Error.to_map("if x then") + + refute String.contains?(map.message, @ansi_escape) + refute String.contains?(map.suggestion || "", @ansi_escape) + + for line <- map.source_context.lines do + refute String.contains?(line.text, @ansi_escape) + end + end + end + + defp error!(code) do + {:error, [error]} = Parser.parse_structured(code) + error + end +end diff --git a/test/lua/parser/parse_structured_test.exs b/test/lua/parser/parse_structured_test.exs new file mode 100644 index 00000000..950fbf71 --- /dev/null +++ b/test/lua/parser/parse_structured_test.exs @@ -0,0 +1,52 @@ +defmodule Lua.Parser.ParseStructuredTest do + use ExUnit.Case, async: true + + alias Lua.AST.Chunk + alias Lua.Parser + alias Lua.Parser.Error + + describe "parse_structured/1 success" do + test "returns the chunk on valid source" do + assert {:ok, %Chunk{}} = Parser.parse_structured("local x = 42\nreturn x") + end + end + + describe "parse_structured/1 errors" do + test "wraps a single converted error struct in a list" do + assert {:error, [%Error{} = error]} = Parser.parse_structured("if x then") + assert error.type == :unexpected_token + assert error.position.line == 1 + end + + test "reports an unclosed delimiter against the opening position" do + assert {:error, [error]} = Parser.parse_structured("local x = (1") + assert error.type == :unclosed_delimiter + assert error.position == %{line: 1, column: 11, byte_offset: 10} + end + + test "surfaces lexer errors as structured errors" do + assert {:error, [error]} = Parser.parse_structured("@") + assert error.type == :invalid_syntax + assert error.message =~ "Unexpected character" + end + + test "reports a bare expression as invalid syntax" do + assert {:error, [error]} = Parser.parse_structured("1 + 1") + assert error.type == :invalid_syntax + assert error.position.column == 3 + end + end + + describe "parse/1 and parse_structured/1 agree" do + # The display and structured paths share `parse_to_error/1`, so the + # formatted string must always reflect the same underlying error. + test "formatted output matches the structured struct's formatting" do + code = "if x then" + + {:error, formatted} = Parser.parse(code) + {:error, [error]} = Parser.parse_structured(code) + + assert formatted == Error.format(error, code) + end + end +end