span-lang 0.4.0

Source positions, spans, and byte-to-line/col mapping for language tooling.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

# span-lang v0.4.0 — Spanned<T>, serde, feature freeze

**The surface, completed and frozen.** v0.4.0 adds the last two pieces of the
0.x design — the `Spanned<T>` wrapper that carries a value alongside its span, and
an optional `serde` feature that round-trips every position type — and then
declares the public API frozen. From here to `1.0.0` there are no new or changed
public items, only documentation, tests, and internal optimisation. No breaking
changes.

## What is span-lang?

The source-position substrate for language tooling. It defines the small,
copyable coordinate types that a lexer, parser, and diagnostic renderer all
share: a byte position, a byte-offset span, a resolved line/column, and the index
that maps between them — correctly over UTF-8, across `\n` and `\r\n`. It owns
positions and nothing else.

## What's new in 0.4.0

### `Spanned<T>` — a value and where it came from

A parser threads spans through every token and node. `Spanned<T>` is the wrapper
that lets a value carry its location without the value type itself knowing
anything about positions — `Copy` whenever `T` is, ordered by span first so a
slice of nodes sorts into source order.

```rust
use span_lang::{Span, Spanned};

// A lexeme: the text "10" at bytes 2..4.
let raw = Spanned::new(Span::new(2, 4), "10");

// `map` lifts it into a typed node, keeping the span.
let parsed = raw.map(|s| s.parse::<u32>().unwrap());
assert_eq!(parsed.value, 10);
assert_eq!(parsed.span, Span::new(2, 4));
```

`map` transforms the value and preserves the span; `as_ref` borrows the value
(yielding `Spanned<&T>`, mirroring `Option::as_ref`) so you can inspect or map it
without consuming the original; `Display` renders `value @ start..end`.

### `serde` — round-tripping positions

Behind the opt-in `serde` feature, every position type derives `Serialize` and
`Deserialize`:

- `BytePos` is `#[serde(transparent)]` — a bare number on the wire, not a wrapper
  object.
- `LineCol` and `Spanned<T>` serialise as structs of their public fields;
  `Spanned<T>` round-trips for any serialisable `T`.
- `Span` has a hand-written `Deserialize` that routes the incoming `{ start, end }`
  through `Span::new`, so a span read from an untrusted source upholds the
  `start <= end` invariant exactly as a constructed one does. An inverted pair on
  the wire is normalised, never accepted as-is — input is validated at the
  boundary, not after.

```rust
use span_lang::Span;

// Inverted on the wire → normalised on the way in.
let s: Span = serde_json::from_str(r#"{"start":10,"end":4}"#).unwrap();
assert_eq!(s, Span::new(4, 10));
assert!(s.start() <= s.end());
```

`tests/serde.rs` round-trips `BytePos`, `Span`, `LineCol`, and `Spanned<T>` (over
both an owned `String` and a scalar) through `serde_json`, and asserts the
inverted-span normalisation. `LineIndex` is deliberately not serialisable: it
borrows a source and is rebuilt from text, not restored from bytes.

### The surface is frozen

With `Spanned<T>` and `serde` in place, the public API is complete and now
**frozen**. `docs/API.md` carries a [Stability](https://github.com/jamesgober/span-lang/blob/main/docs/API.md#stability)
section recording the frozen surface and the SemVer promise from `1.0.0`: no
public item removed or changed incompatibly before `2.0.0`; the serde wire
representations and the `Display` formats are part of the contract; an MSRV
increase is a minor change. The remaining road to `1.0.0` is the full
property-test and benchmark suite green on all three platforms, and nothing else.

## Breaking changes

**None.** `Spanned<T>` and the `serde` feature are purely additive; the feature is
off by default and has no effect on the API when disabled. Every v0.3.0 program
compiles and behaves identically.

## Verification

Run on Windows x86_64, Rust stable 1.95.x and MSRV 1.85; identical commands pass
on Linux (WSL2 Ubuntu) and via the configured CI matrix:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --no-default-features --all-targets -- -D warnings
cargo test
cargo test --all-features
cargo build --no-default-features
cargo build --no-default-features --features serde
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 build --all-features
cargo audit
cargo deny check
```

All green. Counts at this tag:

- Default features: 32 unit + 7 property tests + 26 doctests.
- `--all-features`: 32 unit + 7 property tests + 7 serde tests + 26 doctests.

## What's next

- **1.0.0 — API freeze.** The frozen surface stabilised and tagged: `docs/API.md`
  marked stable, the SemVer promise in force, and the full property-test and
  benchmark suite green on Linux, macOS, and Windows.

## Installation

```toml
[dependencies]
span-lang = "0.4"

# With serialisation:
span-lang = { version = "0.4", features = ["serde"] }
```

MSRV: Rust 1.85.

## Documentation

- [README](https://github.com/jamesgober/span-lang/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/span-lang/blob/main/docs/API.md)
- [CHANGELOG](https://github.com/jamesgober/span-lang/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.3.0...v0.4.0`](https://github.com/jamesgober/span-lang/compare/v0.3.0...v0.4.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/span-lang/blob/main/CHANGELOG.md#040---2026-06-19).