Skip to content

SOURCE_MAPPING.md

Latest commit

 

History

History
92 lines (64 loc) · 3.24 KB

SOURCE_MAPPING.md

File metadata and controls

92 lines (64 loc) · 3.24 KB

Source Mapping (Experimental)

Reflaxe.Elixir’s long‑term goal is to provide .ex.map files that map generated Elixir code back to original Haxe source positions, enabling:

  • better error messages (Haxe file/line from Elixir stacktraces)
  • LLM‑friendly navigation between generated and source code
  • tooling like mix haxe.source_map

Current Status (December 2025)

Source mapping is implemented, but remains experimental:

  • The Haxe‑side writer (src/reflaxe/elixir/SourceMapWriter.hx) is wired into the output phase (src/reflaxe/elixir/ElixirOutputIterator.hx) and emits .ex.map files when enabled.
  • The Elixir‑side lookup module (lib/source_map_lookup.ex) implements Source Map v3 VLQ decoding and can resolve Elixir {file,line,column} back to Haxe positions.

What “experimental” still means

  • Mappings provide full line coverage (every generated line maps to a Haxe position) and add column‑level segments at many expression boundaries (AST node starts).
  • Mappings are still best‑effort:
    • Not every character is mapped (we map expression starts, not identifier “names”).
    • Compiler‑injected lines (bootstrapping, helper shims) map to the nearest reasonable Haxe context.

Non‑alpha / production‑ready status for Reflaxe.Elixir does not require source mapping; it is opt‑in and intended as a debugging aid.

Where the Pieces Live

  • Haxe source map writer (planned emission point):
    • src/reflaxe/elixir/SourceMapWriter.hx
  • Elixir lookup task + runtime helpers:
    • lib/source_map_lookup.ex
    • lib/mix/tasks/haxe.source_map.ex
    • lib/phoenix_error_handler.ex (optional runtime enrichment)

How to Enable

Add a define to your Elixir build:

-D source_map_enabled

Then compile normally. The compiler will emit sibling files:

  • lib/my_module.ex
  • lib/my_module.ex.map

IDE / Editor Workflow (VS Code, etc.)

Elixir tooling (ElixirLS, stacktraces, etc.) does not currently consume .ex.map files automatically. Use the provided Mix task to bridge from a runtime Elixir position back to Haxe.

Find the Haxe source for an Elixir runtime position

mix haxe.source_map lib/my_module.ex 45 12

Open the mapped location in VS Code

code --goto expects 1-based columns, so use the goto output format:

code --goto "$(mix haxe.source_map lib/my_module.ex 45 12 --format goto)"

Reverse lookup (Haxe → Elixir)

If you start from a Haxe location (for example from a type error or a log you emitted), pass a .hx file:

mix haxe.source_map src_haxe/my_module/MyMod.hx 20 0

The task will auto-detect reverse mode for .hx inputs (or you can pass --reverse explicitly).

Recommended Next Steps (If You Want This Feature)

  1. Expand integration coverage
    • Extend the fixture coverage under test/snapshot/core/source_map_* to assert specific mappings (not just structure).
  2. Polish reverse lookup UX
    • If multiple modules reference the same .hx file, consider returning multiple candidate matches in JSON output (or add a --pick flag).
  3. Refine granularity vs size
    • Tune which AST node types emit mapping boundaries to keep .map size reasonable while still mapping meaningful expression starts.