Skip to content
Lyth

ADR 0005: Exact source maps plus column-less `//line` directives

Status: Accepted

Context

Section titled “Context”

Users must see Lyth positions for errors from Lyth, from go/types, from go build, in panics and stack traces, in profilers, and in debuggers.

Decision

Section titled “Decision”
  • Build an exact map (generated byte range → Lyth span) by printing the go/ast, reparsing it, and walking both trees in lockstep. Used for go/types validation errors and tooling.
  • Insert //line file.lyth:N directives without columns at line granularity. The Go compiler, runtime stack traces, delve, and pprof then report Lyth file and line.

Alternatives

Section titled “Alternatives”
  • Columns in directives: verified to be wrong. The column applies to the first byte of the next generated line (indentation included), so columns within differently-shaped generated text are misleading.
  • /*line*/ before every expression: exact, but unreadable output.
  • printer.SourcePos mode with Lyth positions in the AST: couples Go layout to Lyth positions, produces fragile formatting, and emits no columns either.

Consequences

Section titled “Consequences”

Verified in prototypes: go build reports src.lyth:3: (no column), panics print src.lyth:7, absolute directive paths become module/file.lyth under -trimpath, and gofmt keeps directives at column 1 (idempotent).