pmoutils/AGENTS.md

pmoutils - Agent Guidelines

Build & Test Commands

# Build the library
cargo build

# Run all tests (unit + doctests)
cargo test

# Run a single unit test
cargo test --lib ip_utils::tests::test_guess_local_ip

# Run tests for a specific module
cargo test --lib ip_utils::tests

# Run only doctests
cargo test --doc

# Lint with clippy
cargo clippy --all-targets -- -D warnings

# Format code
cargo fmt

Code Style Guidelines

General

• Rust 2024 edition
• Follow official Rust style guide and Clippy recommendations
• All code must be documented with Rustdoc comments
• Prefer &str over String for function parameters when possible

Imports

• Group imports by source: std → external crates → crate modules
• Use use statements at the top of each module
• Import specific items, not glob imports (use std::net::IpAddr, not use std::net::*)

Naming Conventions

• Types: PascalCase (e.g., ProcessPortInfo, TransportProtocol)
• Functions/methods: snake_case (e.g., guess_local_ip, find_process_using_port)
• Constants: SCREAMING_SNAKE_CASE
• Traits: prefix with To or descriptive noun (e.g., ToXmlElement)
• Tests: test_functionality_what_it_does format

Error Handling

• Use Option for operations that may not return a value (e.g., find_process_using_port returns Option<ProcessPortInfo>)
• Use ? operator for propagating errors
• Return default values (like "127.0.0.1") only when appropriate fallback exists
• Document error conditions in function documentation

Types

• Prefer concrete types over generics unless abstraction is needed
• Use u32 for PIDs, u16 for ports
• Use String for process names and owners (owned, mutable)
• Derive Debug and Clone for data structures

Documentation

• All public items require Rustdoc comments
• Include # Examples section when useful
• Document return values and error conditions
• Use triple slashes /// for module-level documentation

Formatting

• Run cargo fmt before committing
• Use 4 spaces for indentation (default Rust formatter)
• Keep lines under 100 characters when possible

Testing

• Unit tests in same file as code (in mod tests {} block)
• Test names follow pattern: test_<function>_<condition>
• Include tests for edge cases (e.g., fallback to localhost)
• Verify return value formats and constraints
• Test filtering: cargo test --lib ip_utils::tests::test_list_all_ips_no_loopback