# `PtcRunner.Lisp.Prelude.ErrorSpan`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/lisp/prelude/error_span.ex#L1)

Resolves a `%PtcRunner.Lisp.Prelude.ValidationError{}` to the byte span of
the top-level form it blames.

`PtcRunner.Lisp.Prelude.Compiler` walks PARSED forms, which carry no source
positions; `PtcRunner.Lisp.Prelude.FormScanner` walks the RAW TEXT and
carries nothing else. This module is the single seam between them, applied
once at the compile boundary so no error site has to know about byte offsets.

## How a failure is located

In order of precision, using whichever locator the error already carries:

  1. `form_index` — the position of the top-level form the compiler was
     processing. `FormScanner.scan/1` cross-checks its own form list against
     `PtcRunner.Lisp.Parser` head-by-head and refuses to return at all on any
     disagreement, so a successful scan is positionally aligned with the
     parsed forms the compiler walked. That check is what makes indexing by
     position safe.
  2. `ref` (`"namespace/symbol"`) — for failures raised after the walk, when
     only the offending definition is known. Resolved to the `def`, `defn`,
     or `defn-` form with that name under that namespace, but only when
     exactly one form matches: a name is unique only once duplicates have
     been rejected, and some ref-carrying failures are raised before that
     check runs. `:duplicate_ref` is the one exception, because it IS the
     duplicate report — it resolves to the last matching form, the
     redefinition that collided.
  3. `namespace` — resolved to the `(ns ...)` form that declares it.

Top-level-form resolution is best-effort and fails OPEN: a source this module
cannot scan, an out-of-range index, or an unresolvable name leaves the error
exactly as it was. That also preserves an explicit parser-position span,
which does not depend on a successful form scan. A diagnostic without a span
is safer than one with a WRONG span pointing at innocent code.

# `resolve`

```elixir
@spec resolve(PtcRunner.Lisp.Prelude.ValidationError.t(), binary()) ::
  PtcRunner.Lisp.Prelude.ValidationError.t()
```

Returns `error` with `span` filled in when the offending top-level form can
be located in `source`, and unchanged otherwise.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
