Rust crate rules

# AGENTS.md: Rust crate

Rust project built with Cargo. Read `Cargo.toml` for the edition and `rust-version` (MSRV) before using newer features.

## Commands
- Build: `cargo build`. Tests: `cargo test` (add `--all-features` if the crate has features).
- Format: `cargo fmt --all -- --check`. Lint: `cargo clippy --all-targets --all-features -- -D warnings`.
- Docs: `cargo doc --no-deps`. Dependency advisories, if installed: `cargo deny check` or `cargo audit`.
- Done means: fmt clean, clippy with no warnings, tests green. Do not silence a lint with `#[allow]` without a comment why.

## Errors
- Library code returns `Result<T, E>` with a typed error enum; no `unwrap()`, `expect()` or `panic!` on input-driven paths.
  `expect("reason")` is fine for true invariants, with the reason saying why it cannot fail.
- Binaries may use `anyhow` for context (`.context("reading config")`). Libraries should not expose `anyhow::Error`.
- Use `?` to propagate. Add context at boundaries, not at every call.

## Safety and dependencies
- `unsafe` only with the human's approval and a `// SAFETY:` comment explaining the invariant. Prefer `#![forbid(unsafe_code)]`.
- Add dependencies with `cargo add <crate>`; check it is maintained and widely used. Keep default features off when you
  only need a small part (`cargo add <crate> --no-default-features --features ...`).
- Never bump the MSRV, edition or a major dependency version as a side effect of another change.

## Style
- Borrow instead of clone; clone only where ownership is genuinely needed, and not to quiet the borrow checker.
  If you fight the borrow checker for more than two attempts, stop and explain the ownership problem.
- Prefer iterators and `match` over index loops and nested `if let`. Keep functions short; name types after the domain.
- Public items get doc comments with an example where it helps; doc tests run with `cargo test`.
- Use the `rust-change` skill for any non-trivial change.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `rust-change`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Rust crate rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/rust-crate/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `rust-change`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Rust crate rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/rust-crate/ -->

---
name: rust-change
description: Make a reviewable Rust change with typed errors, a failing test first for bugs, and fmt, clippy -D warnings and tests before reporting. Use for any non-trivial change to a Rust crate.
---

# Rust change

1. Read the module and its tests. Run `cargo test` once first so you know the baseline.
2. For a bug: write a failing test that reproduces it before touching the code.
3. Model errors as an enum like `references/errors.rs`: one variant per failure the caller can act on, `Display` written
   for humans, `source()` returning the underlying error. `thiserror` is fine if the crate already uses it.
4. Make the change. Keep public API changes out unless asked; if unavoidable, list them in your report.
5. Run, in order: `cargo fmt --all`, `cargo clippy --all-targets --all-features -- -D warnings`, `cargo test`.
   Fix every clippy warning you introduced. Do not add `#[allow(...)]` to pass.
6. Report: what changed, tests added, and the three command results.

//! Typed error pattern without extra dependencies. Callers can match on the variant; humans get a clear message.
//! When copying, change `fixture_crate::errors` in the doc test to your crate and module path.

use std::fmt;
use std::num::ParseIntError;

#[derive(Debug, PartialEq)]
pub enum ConfigError {
    /// A required key is missing.
    Missing(&'static str),
    /// A value could not be parsed.
    BadNumber { key: &'static str, source: ParseIntError },
    /// A value is outside the allowed range.
    OutOfRange { key: &'static str, value: u32, max: u32 },
}

impl fmt::Display for ConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Missing(key) => write!(f, "missing required setting `{key}`"),
            Self::BadNumber { key, .. } => write!(f, "setting `{key}` is not a whole number"),
            Self::OutOfRange { key, value, max } => write!(f, "setting `{key}` is {value}, the maximum is {max}"),
        }
    }
}

impl std::error::Error for ConfigError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::BadNumber { source, .. } => Some(source),
            _ => None,
        }
    }
}

/// Reads the worker count from `key=value` lines.
///
/// ```
/// # use fixture_crate::errors::workers;
/// assert_eq!(workers("workers=4"), Ok(4));
/// ```
pub fn workers(config: &str) -> Result<u32, ConfigError> {
    const KEY: &str = "workers";
    const MAX: u32 = 64;
    let raw = config
        .lines()
        .filter_map(|line| line.split_once('='))
        .find(|(k, _)| k.trim() == KEY)
        .map(|(_, v)| v.trim())
        .ok_or(ConfigError::Missing(KEY))?;
    let value: u32 = raw.parse().map_err(|source| ConfigError::BadNumber { key: KEY, source })?;
    if value > MAX {
        return Err(ConfigError::OutOfRange { key: KEY, value, max: MAX });
    }
    Ok(value)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn reads_value() {
        assert_eq!(workers("name=x\nworkers = 8\n"), Ok(8));
    }

    #[test]
    fn missing_key() {
        assert_eq!(workers("name=x"), Err(ConfigError::Missing("workers")));
    }

    #[test]
    fn bad_number_keeps_source() {
        let err = workers("workers=lots").unwrap_err();
        assert!(matches!(err, ConfigError::BadNumber { .. }));
        assert!(err.source().is_some());
        assert_eq!(err.to_string(), "setting `workers` is not a whole number");
    }

    #[test]
    fn out_of_range() {
        assert_eq!(workers("workers=100"), Err(ConfigError::OutOfRange { key: "workers", value: 100, max: 64 }));
    }
}