# Repository Guidelines
## Project Structure & Module Organization
The crate root (`Cargo.toml`) exposes production code from `src/lib.rs`, while the CLI playground in `src/main.rs` demonstrates parsing and formatting of network objects. Domain modules live under `src/ip/` (`network.rs`, `range.rs`, `fqdn.rs`) with one-type-per-file organization so new object types can be added by creating a sibling module and re-exporting it in `src/ip/mod.rs`. Standalone helpers such as `address.rs` sit in the repository root; prefer moving new shared types into `src/` to keep the crate API discoverable. Integration tests can live in `tests/` (create as needed), and doctests already embedded in the modules are run automatically.
## Build, Test, and Development Commands
- `cargo fmt` — format the entire workspace; run before pushing and wire it into pre-commit hooks if available.
- `cargo clippy --all-targets --all-features` — lint for correctness and style issues; treat warnings as actionable.
- `cargo test` — executes unit tests, doctests, and any future files under `tests/`; add `-- --nocapture` to inspect parser output.
- `cargo run --bin firewall-objects` — runs the sample CLI in `src/main.rs`, handy for validating new parsing behaviors with real strings.
## Coding Style & Naming Conventions
Use the default Rust 2024 formatting (4-space indents, 100-character lines) enforced by `rustfmt`. Expose modules with snake_case filenames (`src/ip/network.rs`) and PascalCase types (`NetworkObj`, `IpRange`), keeping enums and structs small and focused. Derive comparison and ordering traits whenever objects participate in `BTreeSet` collections, and prefer builder-style constructors such as `NetworkObj::new`. Document behavior with triple-slash doc comments plus runnable examples so `cargo test` can verify them. Keep imports sorted by std, third-party (`ipnet`), then internal modules.
## Testing Guidelines
Augment the existing doc tests with targeted unit tests by adding `#[cfg(test)] mod tests { ... }` at the bottom of each file; name tests after the scenario, e.g., `fn range_rejects_backwards_span()`. Favor table-driven data for IPv4, IPv6, range, and FQDN parsing to increase coverage quickly. Run `cargo test --doc` before submitting if you worked primarily on documentation, and ensure new public APIs include at least one doctest or integration test.
## Commit & Pull Request Guidelines
Follow the existing concise style (`Firewall Object crate - initial commit.`) by writing a short, imperative summary that explains what changed and why; include scope prefixes when useful (`parser:` or `docs:`). Each PR should describe the change, reference any GitHub issues using `Fixes #123`, and list validation commands (`cargo fmt && cargo clippy && cargo test`). Attach CLI output or screenshots when adding user-facing behavior, and call out follow-up work explicitly so reviewers can track it.