source-lang 1.0.0

Source file and buffer management with multi-file source maps.
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

# source-lang v0.4.0 — serde & feature freeze

**The surface is set.** v0.2.0 built the core, v0.3.0 made it loadable. v0.4.0 adds
the last planned capability — optional `serde` so a whole source map can be
persisted and restored — and then freezes the public API. From here to `1.0.0`
there are no new public items, only documentation, tests, and internal work; `1.0.0`
ratifies this surface and holds it stable until `2.0`.

## What is source-lang?

The multi-file coordinate layer of a compiler front-end. It loads files and
in-memory buffers, gives each a stable `SourceId`, lays them out in one global
position space, and maps any global position back to the source and local offset —
or the file, line, and column — it came from. It is the layer above `span-lang`: a
`Span` says *where in a buffer* an error is, source-lang says *which buffer*. It owns
source storage and coordinate mapping only.

## What's new in 0.4.0

### `serde` for the source map

With the `serde` feature, `SourceMap` and `SourceId` implement `Serialize` and
`Deserialize`, and the re-exported coordinate types carry their `span-lang` serde
implementations. A map round-trips through any serde format:

```rust,ignore
let mut map = SourceMap::new();
map.add("main.rs", "fn main() {}")?;
map.add("util.rs", "let x = 1;\nlet y = 2;")?;

let json = serde_json::to_string(&map)?;
let restored: SourceMap = serde_json::from_str(&json)?;

assert_eq!(map, restored);
assert_eq!(restored.line_col(BytePos::new(23)).unwrap().1.line, 2);
```

The wire form is deliberately small: the list of sources — each a name and its text
— plus the size ceiling. Everything the map derives (each source's span, its id, the
global high-water mark) is left out and **regenerated on load**, by replaying the
sources through the same insertion path as `add`.

That choice is what makes deserialisation safe. The layout is rebuilt, not trusted,
so a hand-edited or corrupted document cannot smuggle in overlapping ranges or a
broken coordinate space; a source list whose combined length overruns the 32-bit
space is a deserialisation error, not a silently broken map. The `max_source_len`
field is optional on read, so a document written by an earlier build still loads.

A `SourceId` serialises transparently as its `u32` index, so a handle stored in an
AST node or a cached diagnostic round-trips on its own.

### `PartialEq` / `Eq` for `SourceMap`

Two maps compare equal when they hold the same sources in the same layout with the
same ceiling — useful for tests and for confirming a round-trip preserved the map.

### Public API frozen

This release declares the public surface frozen. No public items will be added or
changed before `1.0.0`. `docs/API.md` is marked accordingly. The frozen surface is
the complete source map: construction, the three loaders (`add`, `add_bytes`,
`add_file`), resolution (`locate`, `line_col`, `source`, `iter`), the size ceiling,
`SourceFile` and its `line_index`, `SourceId`, `SourceMapError`, and the re-exported
coordinate types.

## Breaking changes

**None.** Everything in this release is additive: the new trait implementations are
gated behind the `serde` feature, and `PartialEq`/`Eq` add no constraints to existing
code.

## Verification

Run on Windows x86_64 (Rust stable and 1.85 MSRV); the same commands run on Linux
(WSL2 Ubuntu) and across the CI matrix on Linux, macOS, and Windows:

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

All green. Counts at this tag:

- `--all-features`: 27 unit + 6 file-loading + 5 property + 5 serde + 23 doctests.
- Default features: identical minus the serde integration tests.

The serde round-trip is covered in `tests/serde.rs`: a populated map (including a
multi-byte source and a zero-width source) survives a JSON round-trip with its ids,
spans, and line/column resolution intact, a bare `SourceId` round-trips on its own,
and a document missing the ceiling field loads with the default.

## What's next

- **1.0.0 — API freeze.** The surface declared frozen here becomes the stable `1.0`
  contract: documentation, the full property-test and benchmark suite green on all
  three platforms, and a recorded SemVer promise.

## Installation

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

Enable serialization with:

```toml
[dependencies]
source-lang = { version = "0.4", features = ["serde"] }
```

MSRV: Rust 1.85.

## Documentation

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

---

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