Skip to content

feat(parser): expose structured parse errors (parse_structured + Error.to_map) - #363

Merged
davydog187 merged 2 commits into
mainfrom
feat/structured-parse-errors
Jun 14, 2026
Merged

davydog187 merged 2 commits into
mainfrom
feat/structured-parse-errors

Conversation

@davydog187

Copy link
Copy Markdown
Contributor

Closes #361.

Lua.Parser computed rich, structured error data internally but only exposed it as a pre-formatted ANSI display string. Tooling that renders parse errors in its own UI (editors, LSPs, web frontends) had to either scrape that string or match parse_raw/1's raw internal tuples — neither a stable contract. This exposes the structured data directly.

Changes

  1. Lua.Parser.parse_structured/1 → {:ok, Chunk.t()} | {:error, [%Lua.Parser.Error{}]}. Returns the converted error struct(s) instead of a display string. The list shape leaves room for multi-error recovery without a future breaking change. parse/1 and parse_structured/1 now share a private parse_to_error/1, so the display and structured paths cannot drift.

  2. Lua.Parser.Error.to_map/1 and /2 — a JSON-serializable map with the same wire shape as Lua.VM.ErrorFormatter.to_map/3 (type, message, source, line, call_stack, source_context: %{lines, pointer_column}, suggestion, error_kind), so runtime and parse errors can flow through a single renderer. Trailing newlines from the internal templates are trimmed; no ANSI escapes appear in any field. A named @type wire_error pins the shape for dialyzer.

  3. Bonus (proposal item 3): source_context.pointer_column is populated from the real position.column, so the ^ marker lands on the offending token instead of always column 1.

Deliberately out of scope

  • parse_raw/1 unchanged — repurposing it would break its existing {:error, term()} contract.
  • No top-level Lua.parse_chunk_structured/1 — that path also folds in compiler string-errors; separable and messier. The Lua.Parser-level API is the clean primitive.
  • related errors omitted from the wire map — never populated today, and including them would diverge from ErrorFormatter shape parity.

Verification

  • Full suite: 2427 passed (incl. 1 new doctest + 15 new unit tests across error_to_map_test.exs and parse_structured_test.exs), 7 skipped.
  • mix dialyzer: 0 errors.
  • mix format clean.
  • A test asserts key-for-key parity with Lua.VM.ErrorFormatter.to_map/3.

🤖 Generated with Claude Code

…r.to_map)

Tooling that wants to render parse errors in its own UI had to either
scrape parse/1's formatted string or match parse_raw/1's internal tuples.
Neither is a stable contract.

- Lua.Parser.Error.to_map/1,2 emits a wire-safe map with the same shape
  as Lua.VM.ErrorFormatter.to_map/3, so runtime and parse errors share one
  renderer. pointer_column is derived from the real position.column.
- Lua.Parser.parse_structured/1 returns {:ok, Chunk} | {:error, [%Error{}]}.
- parse/1 and parse_structured/1 share parse_to_error/1 so the display and
  structured paths cannot drift.

Closes #361
- Reword to_map/2 docs: "leading/trailing whitespace is trimmed" to match
  clean/1's String.trim/1 behavior.
- Drop "| nil" from the doc's source_context.pointer_column; it is always a
  pos_integer when source_context is present.
- Note build_source_context deliberately mirrors ErrorFormatter's windowing.
- Add a test pinning source_context (and lines[] element) keys against
  Lua.VM.ErrorFormatter.to_map/3, not just the top-level keys.
@davydog187
davydog187 merged commit 7ecbf42 into main Jun 14, 2026
5 checks passed
@davydog187
davydog187 deleted the feat/structured-parse-errors branch June 14, 2026 16:33
This was referenced Jun 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose structured parse errors (public struct + to_map) for programmatic consumers

1 participant