Repository Guidelines

Project Structure & Module Organization

• src/main.rs: Single-binary entrypoint and core pipeline (listener collection, Docker enrichment, rendering).
• docs/CODE_READING_GUIDE.md: Architecture and safe modification path for parser/join/output logic.
• README.md: User-facing install and usage examples.
• target/: Build artifacts (generated; do not edit).

Keep core logic in focused functions (for example parse_lsof_line, parse_docker_ps_line, build_docker_lookup) and avoid splitting into extra modules unless complexity clearly requires it.

Build, Test, and Development Commands

• cargo run --quiet: Run the CLI locally.
• cargo test: Run unit tests in src/main.rs.
• cargo fmt: Apply standard Rust formatting.
• cargo clippy --all-targets --all-features -D warnings: Enforce lint cleanliness.
• cargo build --release: Build optimized binary.
• cargo install --path .: Install local development build.

Typical local validation flow: cargo fmt && cargo clippy --all-targets --all-features -D warnings && cargo test

Coding Style & Naming Conventions

• Follow rustfmt defaults (4-space indentation; no manual alignment hacks).
• Use snake_case for functions/variables and CamelCase for structs.
• Prefer descriptive, behavior-based function names (collect_*, parse_*, format_*).
• Keep error messages explicit and actionable (lsof failed: ..., docker ps failed: ...).
• Preserve deterministic output behavior (sorted rows, stable formatting).

Testing Guidelines

• Place unit tests in #[cfg(test)] mod tests within src/main.rs.
• Name tests as function_behavior_expected_outcome (example: parse_lsof_ipv6_loopback).
• Add/adjust tests before changing parser or matching behavior.
• Ensure cargo test passes before opening a PR.

Commit & Pull Request Guidelines

• Commit style in history is concise, imperative, and optionally scoped:
  • docs: add code reading guide
  • fix process name
• Keep commits single-purpose; avoid mixing refactors with behavior changes.
• PRs should include:
  • What changed and why.
  • User-visible impact (sample output if CLI behavior changed).
  • Validation performed (cargo test, cargo clippy, etc.).
  • Linked issue (if applicable).

Security & Runtime Notes

• The CLI shells out to lsof and docker; handle missing/failed commands gracefully.
• Do not assume Docker is available; preserve fallback behavior that still prints local listeners.