# Repository Guidelines
This Rust 2024 library provides provider-independent, server-side CAPTCHA verification. Preserve its small, feature-gated design.
## Repository Structure
- `src/` contains core types; public exports belong in `src/lib.rs`.
- `src/providers/` contains one feature-gated module per CAPTCHA provider. Keep provider-specific behavior isolated there.
- `tests/` contains integration tests. Unit tests may live beside the implementation when they exercise private behavior.
- `docs/architecture/` records the target architecture and design decisions, not necessarily the current ABI.
- CI and dependency policy live in `.github/workflows/`, `.config/nextest.toml`, and `deny.toml`.
## Working Rules
- Read nearby code, tests, and relevant architecture notes before changing behavior. Follow existing module and error patterns.
- Keep diffs reviewable. Do not combine behavior changes, broad cleanup, and dependency upgrades unless requested.
- Preserve unrelated local changes and never commit generated `target/` artifacts.
- Propose new dependencies first. Keep optional integrations behind Cargo features and update `all-providers` when adding a provider.
- Maintain the current MSRV (Rust 1.88) unless the task explicitly changes it.
## Checks
Run the narrowest relevant checks, then the standard suite before handing off:
```bash
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo nextest run --workspace --all-features --locked
```
For feature or public-API changes, also check `--no-default-features`, affected provider features, and doctests.
## Rust Style
- Use rustfmt, standard Rust naming, and field-init shorthand.
- Prefer private modules with explicit public re-exports.
- Return typed `Result` errors instead of panicking. Make `match` expressions exhaustive when practical.
- Avoid ambiguous boolean or `Option` parameters in public APIs; prefer enums, builders, or named option types.
- Document public items and new trait expectations.
- Prefer focused modules over large files.
- Unsafe code is forbidden. All Clippy `all` and `pedantic` warnings must pass.
## Testing and Security
- Write focused, behavior-named tests such as `provider_configs_redact_secrets_from_debug_output`.
- Integration tests belong in `tests/`. Cover changed contracts and feature boundaries.
- Never expose secrets, tokens, API keys, private keys, or HMAC keys through logs, errors, serialization, or `Debug`; add regression tests for security fixes.
## Commits and Releases
- Use focused Conventional Commits
- Do not edit `CHANGELOG.md` for ordinary changes; `release-plz` owns changelog and version updates in its release PR.
- Pull requests should explain API or feature impact, link relevant issues or ADRs, and include appropriate tests.