# span-lang v0.1.0 — Scaffold

**The repository bootstrap.** v0.1.0 stands up the crate, the tooling, and the
quality gates the implementation is built on — and nothing more. There is no
domain logic in this release on purpose: the position and span types, the UTF-8
line/column resolver, the line index, and the `Spanned` wrapper land across the
0.x series, each behind a passing gate. This tag exists so that the first line of
real code is written against a green CI, a fixed toolchain contract, and a
documented plan, rather than into an empty directory.

## 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: loading source is `source-lang`, rendering an error
that points at a span is `diag-lang`. It is the bottom crate of the `-lang`
language-construction family; everything above it references its types on every
token and every error.

## What's in 0.1.0

### Crate manifest and toolchain contract

`Cargo.toml` declares the full publish metadata — description, keywords,
categories, repository, homepage, dual `Apache-2.0 OR MIT` license, and authors —
on Rust 2024 edition with MSRV 1.85. The feature set is minimal and additive:
`std` on by default, with an opt-in `serde` feature reserved for serialising the
position types as they land. The crate carries no first-party dependencies, so it
builds and tests standalone today.

### Quality gates, wired before the code

The CI matrix (`.github/workflows/ci.yml`) runs the full gate on Linux, macOS,
and Windows against both stable and the 1.85 MSRV: `cargo fmt --check`, clippy on
default and all features with `-D warnings`, the test suite on both feature sets,
and a documentation build with `-D warnings`. A separate security job runs
`cargo audit` and `cargo deny check`. `deny.toml`, `clippy.toml`, and
`rustfmt.toml` pin the license allow-list, the lint profile, and the
import-grouping style. The crate root sets `#![forbid(unsafe_code)]` and
`#![deny(missing_docs)]` from the first commit, and is `no_std`-ready behind the
`std` feature.

### Documentation and plan

`README.md` and `docs/API.md` describe the intended surface and mark each item
still planned, so the public contract is legible before it is implemented.
`dev/DIRECTIVES.md` records the definition of done and the project-specific
invariants the property tests will hold to: a span's start never exceeds its end;
`merge` is associative and commutative and covers exactly the smallest enclosing
range; line/column resolution is UTF-8-correct and round-trips against a naive
reference. `dev/ROADMAP.md` front-loads the hard part — the UTF-8 line/column
resolver and its `O(log lines)` index at v0.2.0 — and carries an anti-deferral
rule: no listed hard task slips to a later phase without the file recording the
move and the reason.

## Breaking changes

**None.** This is the first tag.

## Verification

```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
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 build --all-features
cargo audit
cargo deny check
```

Counts at this tag: 1 unit test (a build smoke test), 0 doctests — there is no
public surface to exercise yet.

## What's next

- **0.2.0 — Core position & span types.** `BytePos`, a compact `Copy` `Span`, and
  the UTF-8-correct line/column resolver with its `O(log lines)` index. Invariants
  come under property tests against a naive reference. This is the hard part, and
  it is not deferred.

## Installation

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

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)

---

**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/span-lang/blob/main/CHANGELOG.md).
