pmoutils/AGENTS.md

pmoutils - Agent Guidelines

Build & Test Commands

# Navigate to the utils directory first
cd pmoutils

# 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 2021 edition
• Follow official Rust style guide and Clippy recommendations
• All code must be documented with Rustdoc comments (triple slash ///)
• Prefer &str over String for function parameters when possible
• Use French documentation comments (match project convention)

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
• 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 from fallible functions
• Return default values (like "127.0.0.1") only when appropriate fallback exists
• Document error conditions in function documentation

Dependencies

• get_if_addrs: Network interface address detection
• os_info: Cross-platform OS version detection
• netstat2: Network socket and process port mapping
• sysinfo: Process and system information
• users: User lookup by UID

Platform Support

• Currently targets Unix-like systems (macOS, Linux)
• Socket info retrieval uses netstat2 which may have limited Windows support
• OS detection is cross-platform via os_info crate

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

Module Organization

• ip_utils.rs: Network IP address utilities (detection, listing)
• process.rs: Process and port information utilities
• Export public functions at crate root in lib.rs
• Group related functionality into modules with clear responsibilities

Additional Notes

• The project uses French documentation comments throughout
• Doctests are included and tested via cargo test --doc
• Test helper functions (like is_private_ip) can be included in the tests module
• Prefer explicit error handling with clear fallback behavior