Contributing

carrel is written in Rust. The code is a library (src/lib.rs and its modules) with three frontends: the CLI (src/main.rs), the TUI (src/tui.rs) and the MCP server (src/mcp.rs).

Setup

With Nix, nix develop gives you Rust, clippy, rustfmt, rust-analyzer, mdBook and uv. Otherwise install a recent Rust (1.88 or newer) and uv.

cargo run -- --help
cargo fmt && cargo clippy --all-targets -- -D warnings

Tests

cargo test                  # offline: unit tests, the library, the CLI binary and the MCP server
cargo test -- --ignored     # the tests that need internet (and uv), in tests/network.rs

The internet tests are marked #[ignore = "needs internet"], so a plain cargo test, which is also what the Nix build runs in its sandbox, skips them. The offline tests use a fake extractor and keep their library, index and config in a temporary folder, so they need neither Python nor a home directory. Semantic Scholar and arXiv rate-limit; if internet tests fail with a 429, set S2_API_KEY or wait a few minutes.

Docs

This site is an mdBook in docs/:

mdbook serve docs --open

Releases

Commit messages follow Conventional Commits: fix: makes a patch release, feat: a minor one, a ! (or BREAKING CHANGE:) a major one (before 1.0: a minor one). On every push to main, release-please keeps a release pull request with the next version and changelog up to date; merging it tags the release, and the release workflow attaches binaries for Linux (x86_64, arm64) and macOS (Apple silicon).