gitpane AGENTS.md

AGENTS.md

Guidance for AI coding agents working on gitpane, a multi-repo Git workspace dashboard TUI (Rust, ratatui). For the human-facing overview, see README.md.

Setup

• Rust edition 2024, MSRV 1.88.0. Install a matching toolchain (rustup recommended).
• No services or network access are needed to build, run, or test.
• Optional tooling for the full local suite: cargo install cargo-audit cargo-llvm-cov, plus just for the task recipes below.

Build and run

just run                 # or: cargo run
cargo build --release

Checks (run before every commit)

just ci                  # fmt + lint + docs + test, the full gate
# or individually:
just fmt                 # cargo fmt --all
just lint                # cargo clippy --all-targets --all-features -- -D warnings
just test                # cargo test --all-targets --all-features
just docs                # rustdoc with -D warnings

CI runs the same checks and treats every warning as an error, so just ci must pass before you push. Tests are inline #[cfg(test)] modules in the binary target, so a plain cargo test --lib finds nothing. Use just test or cargo test --bin gitpane.

Pre-commit hooks (required)

Install them before contributing:

pre-commit install       # installs the pre-commit and pre-push hooks

The pre-commit hook runs file hygiene, TOML/YAML checks, cargo fmt, cargo clippy, and the two project rules below. The pre-push hook runs tests, audit, docs, and coverage.

Hard constraints

• Every source file stays under 1000 lines. When a file approaches the limit, split it: turn foo.rs into a foo/ directory module and re-export the public items from foo/mod.rs so external paths such as crate::foo::Bar do not change. Do not add exclude lists to dodge the limit; split the file.
• Every directory under src/ holds at most 10 files. Group related modules into a subfolder rather than letting a folder sprawl. A subfolder's files count toward the subfolder, not its parent.
• No warnings. clippy runs with -D warnings. Fix the cause; do not paper over it with #[allow(...)] unless there is a documented reason.
• Refactors that relocate code must be behavior preserving: keep the move mechanical, re-export to preserve public paths, and keep the test count identical.