syntax-lang 1.0.0

# syntax-lang v1.0.0 — API freeze

**Stable.** v1.0.0 freezes the public API. The tree, the builder, and the
traversals built in 0.2.0 are now under a Semantic Versioning promise: no breaking
change before `2.0`, additions only in minor releases, MSRV (Rust 1.85) rising only
in a minor. There are no functional API changes from `0.2.0`; this release is the
commitment.

## What is syntax-lang?

The lossless-CST layer of the `-lang` family — the substrate a formatter, a
language server, or a tree-sitter-style generator builds on. It owns no grammar: a
language brings its own kind type, stores nodes and leaf tokens in the tree, and
syntax-lang supplies the [`Builder`] that assembles it and the walks over it.
Whitespace and comments ride as ordinary leaf tokens, so the tree reproduces the
source byte for byte; tokens carry spans rather than copies of the text, so
reconstruction is a zero-copy borrow.

## The frozen surface

- **`Node<K>`** — `new`, `kind`, `span`, `is_empty`, `len`, `children`,
  `child_nodes`, `child_tokens`, `descendants`, `tokens`, `text`.
- **`Element<K>`** — the `Node` / `Token` child, with `span`, `kind`, `as_node`,
  `as_token`, `is_node`, `is_token`.
- **`Builder<K>`** — `start_node` / `token` / `finish_node` / `finish`, plus
  `new` / `is_empty` / `Default`.
- **`BuildError`** — the five structural faults (`#[non_exhaustive]`), `Display`,
  `core::error::Error`.
- **Re-exports** — `Token`, `TokenKind`, `Symbol` (token-lang) and `Span`,
  `Spanned` (span-lang).

The full reference, the SemVer promise, and what is deliberately left out (a
`serde` feature, mutable/fallible traversal, builder checkpoints — all addable
later without a breaking change) are in
[`docs/API.md`](https://github.com/jamesgober/syntax-lang/blob/main/docs/API.md).

## Guarantees

- **Lossless.** Concatenating a node's `tokens()`, or slicing the source by its
  `span()`, reproduces the node's source exactly — trivia included.
- **Covering span.** A node's span is the union of its children's spans; the leaf
  stream tiles that span with no gaps or overlaps.
- **Stack-safe.** `Builder`, `tokens()`, `descendants()`, and `Drop` are iterative
  — a 200,000-level tree is built, walked, and freed without recursing on the call
  stack, so untrusted deeply-nested input cannot turn into a crash.
- **Non-panicking builder.** Structural misuse is reported as a `BuildError` from
  `finish`, never a panic.
- **`no_std`** with `alloc`; `#![forbid(unsafe_code)]`; no `unwrap` / `expect` /
  `todo!` in shipping code.

## Breaking changes

**None.** Identical API to `0.2.0`. From here, breaking changes require `2.0`.

## Verification

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --no-default-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 on Windows and Linux (WSL2 Ubuntu). Counts: 19 unit + 10 behavioural + 6
property + 28 doctests.

## Installation

```toml
[dependencies]
syntax-lang = "1"
```

MSRV: Rust 1.85.

---

**Full diff:** [`v0.2.0...v1.0.0`](https://github.com/jamesgober/syntax-lang/compare/v0.2.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/syntax-lang/blob/main/CHANGELOG.md#100---2026-07-01).