# source-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 source map, the stable ids, the
global position space, file loading, and line integration 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 source-lang?

The text-management layer for 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 file and local offset it came
from. It is the multi-file coordinate layer above `span-lang`: spans say *where in
a buffer*, source-lang says *which buffer*, so a diagnostic can name the file as
well as the position. It owns source storage and coordinate mapping only —
tokenising is `lexer-lang`, rendering is `diag-lang` — and it is one of the
foundation crates of the `-lang` language-construction family.

## 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 (for file loading), with an opt-in `serde` feature reserved
for source-map metadata. No first-party dependency is wired yet; `span-lang` is
added at v0.2.0 when the coordinate code first uses it, so the scaffold carries no
unused dependency.

### 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.

### 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: every source gets a unique, stable
id; sources occupy non-overlapping global ranges; a valid global position maps to
exactly one `(SourceId, local offset)` and round-trips. `dev/ROADMAP.md`
front-loads the hard part — the global position space and its `O(log files)`
resolver at v0.2.0, where `span-lang` is also wired — 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 — Source storage & global position space.** Wire `span-lang`; build the
  `SourceMap`, stable `SourceId`s, and the non-overlapping global range layout with
  an `O(log files)` resolver. Non-overlap, unique-id, and round-trip come under
  property tests against a naive scan. This is the hard part, and it is not deferred.

## Installation

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

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)

---

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