monocle: Instructions file for Codex

Monocle - Agent Instructions

This document provides guidelines for AI coding agents working on the monocle codebase.

Build, Lint, and Test Commands

Quick Reference

# Format code (always run after editing)
cargo fmt

# Build with default features (cli)
cargo build

# Run all tests
cargo test --all-features

# Run clippy with all warnings as errors
cargo clippy --all-features -- -D warnings

# Run a single test by name
cargo test test_name
cargo test lens::time::tests::test_parse_unix

# Run tests for a specific module
cargo test lens::rpki

# Run tests with output visible
cargo test test_name -- --nocapture

CI Checks (run before committing)

The GitHub Actions workflow runs these checks on PRs:

cargo fmt --check              # Check formatting
cargo clippy --all-targets --all-features -- -D warnings  # Lint
cargo test --all-features --verbose         # All tests

Code Style Guidelines

Lints

The crate enforces strict lints in lib.rs:

#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]

Use ? operator or explicit error handling instead of .unwrap() or .expect().

Import Organization

Group imports in this order, separated by blank lines:

1. Standard library (std::)
2. External crates
3. Internal crate modules (crate::, super::)

Naming Conventions

Item	Convention	Example
Lens struct	{Name}Lens	TimeLens, RpkiLens, InspectLens
Args struct	{Name}{Op}Args	TimeParseArgs, RpkiValidationArgs
Result struct	{Name}{Op}Result	As2relSearchResult, InspectResult
Module name	snake_case	as2rel, pfx2as, inspect
Constants	SCREAMING_SNAKE_CASE	DEFAULT_RPKI_CACHE_TTL

Error Handling

Use anyhow::Result for lens methods with descriptive error messages:

// Good
Err(anyhow!("Invalid prefix format: {}. Expected CIDR notation (e.g., 1.1.1.0/24)", input))

// Bad
Err(anyhow!("invalid input"))