# Contributing to Surelock
## Prerequisites
This project uses [Nix](https://nixos.org/) for reproducible development environments.
```sh
nix develop
menu # list available commands
```
## Building
```sh
cargo build
cargo build --all-features
cargo build --no-default-features # no_std check
```
## Testing
```sh
cargo test # all tests (unit, integration, doc, property, compile-fail)
cargo test --doc # doc tests only
cargo test --test integration # integration tests only
cargo test --test property # property tests (bolero)
cargo test --test compile_fail # compile-fail tests (trybuild)
```
## Linting
```sh
cargo clippy --all-targets
cargo clippy --all-targets --all-features
cargo fmt --check
cargo doc # check for doc warnings
```
## Project Structure
```
src/
├── acquirable.rs Acquirable<'a> trait (internal)
├── acquirable/tuples.rs Tuple impls 2-12
├── id.rs LockId
├── key.rs MutexKey, lock_scope, try_lock_scope
├── key_handle.rs KeyHandle
├── key_voucher.rs KeyVoucher
├── level.rs Level<N>, IsLevel, LockAfter, etc.
├── locksmith.rs Locksmith
├── mutex.rs Mutex<T, Lvl, R>
├── mutex/guard.rs MutexGuard
├── raw_mutex.rs RawMutex trait
├── raw_mutex/std_mutex.rs StdMutex backend
├── raw_mutex/lock_api_adapter.rs lock_api bridge
└── set.rs LockSet
tests/
├── integration.rs Full lifecycle tests
├── lock_order.rs Level declaration tests
├── compile_fail.rs Compile-fail test runner
├── compile_fail/*.rs Individual compile-fail cases
└── property.rs Property tests (bolero)
design/ Published design docs
├── README.md Architecture overview
├── ROADMAP.md Planned features for v2+
└── comparison/ Comparisons with prior art
.ignore/ Internal design notes (gitignored, not published)
├── CONTEXT.md Codebase overview
├── DESIGN.md Architecture reference
├── DECISIONS.md ADRs (Architecture Decision Records)
├── ALTERNATIVES.md Approaches considered
├── TODO.md Task list
└── CRITICAL_SECTION_BACKEND.md no_std backend sketch
```
## Unsafe Policy
`#![deny(unsafe_code)]` at the crate level. Only modules that
need `unsafe` opt in via `#![allow(unsafe_code)]`:
- `raw_mutex.rs` -- `unsafe trait RawMutex`
- `raw_mutex/std_mutex.rs` -- `unsafe impl` for StdMutex
- `raw_mutex/lock_api_adapter.rs` -- blanket `unsafe impl`
- `mutex.rs` -- `unsafe impl Send/Sync`
- `mutex/guard.rs` -- `Deref`/`DerefMut` on `UnsafeCell`
- `key_voucher.rs` -- `unsafe impl Send`
All other modules are fully safe. Adding `unsafe` to a new module
requires justification.
## Naming Conventions
| Factory | `Locksmith` | `smith` |
| Voucher | `KeyVoucher` | `voucher` |
| Per-thread | `KeyHandle` | `handle` |
| Scope key | `MutexKey` | `key` |
| Guard | `MutexGuard` | `guard` |
| Lock group | `Acquirable` | -- |
| Pre-sorted | `LockSet` | `set` |
## Adding a New Level Trait
Level impls are generated by macros in `src/level.rs`. To change
the default count or add a new trait to the level system:
1. Update the `generate_level_impls!` macro
2. Update the `#[cfg]` blocks for feature-gated counts
3. Run `cargo test` -- property tests verify level ordering invariants
## Adding a New Tuple Arity
Tuple `Acquirable` impls are in `src/acquirable/tuples.rs`. The
2-tuple supports multi-level (different `Lvl` per element); arities
3-12 require same level. To add a multi-level impl for higher
arities, see the 2-tuple impl as a reference.
## Compile-Fail Tests
Compile-fail tests use `trybuild`. Each test case is a `.rs` file in
`tests/compile_fail/` with a corresponding `.stderr` file. To update
expected output after a change:
```sh
TRYBUILD=overwrite cargo test --test compile_fail
```
## Design Documents
Published design docs live in `design/`:
- `design/README.md` -- architecture overview and design principles
- `design/ROADMAP.md` -- planned features for v2+
- `design/comparison/` -- detailed comparisons with `happylock` and `lock_tree`
Internal design notes live in `.ignore/` (gitignored, not published):
- `DECISIONS.md` -- numbered ADRs with rationale
- `DESIGN.md` -- architecture reference
- `TODO.md` -- task list with checkbox notation
When making design decisions, add an ADR to `.ignore/DECISIONS.md`.