saneyaml 0.3.0

Pure-Rust YAML parser, emitter, and Serde compatibility layer for developer configuration files.
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

# Architecture

## Package and Library Names

The crates.io package name and the Rust library target are both `saneyaml`, so
downstream code imports this crate as `saneyaml::...`:

```toml
[dependencies]
saneyaml = "0.3.0"
```

For drop-in `serde_yaml` migration, Cargo dependency renaming keeps existing
source imports intact:

```toml
[dependencies]
serde_yaml = { package = "saneyaml", version = "0.3.0" }
```

or a local source alias:

```rust
use saneyaml as serde_yaml;
```

## Monolith Decision

`saneyaml` is one crate for the first public release. It is not a crate family
and does not publish separate `yaml-core`, `yaml-value`, `yaml-serde`, or
`yaml-edit` packages.

The parser, tree model, deserializer, emitter, and lossless source model are
tightly coupled today. In particular, `parse.rs` and `de.rs` share reader
ingestion, limits, schema construction, merge behavior, and span diagnostics.
Splitting those seams before real downstream adoption would create compatibility
and versioning surfaces without reducing meaningful user complexity.

The monolith keeps one SemVer contract, one feature map, one diagnostics model,
and one package alias story for `serde_yaml` migration.

## Feature Facade

The only optional crate feature currently exposed is:

```toml
default = ["lossless"]
lossless = []
```

`lossless` controls source-backed graph inspection and format-preserving edit
helpers. Serde integration, `Value`, structural writers, and emitter controls
are always part of the package contract because `serde` is a runtime dependency
and the migration surface is not currently split into optional subfeatures.
Future feature narrowing should add real `cfg(feature = "...")` boundaries,
tests, and documentation instead of naming facade features that do not alter
compiled API.

## Stability Boundary

The crate is pre-1.0. Public exports, public enum variants, public struct
fields, feature names, package metadata, MSRV, and the package-vs-library name
split are still SemVer-visible for adopter trust. Intentional changes to those
surfaces must update `docs/PUBLIC_API.txt`, `docs/MIGRATION.md`,
`docs/COMPATIBILITY.md`, and the baseline evidence rather than relying on
silent drift.