pmoutils/AGENTS.md

# pmoutils - Agent Guidelines

## Build & Test Commands

```bash
# 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