1c04e1314d
Clarifies codex-rs testing approvals in AGENTS.md: - Allow running project-specific or individual tests without asking. - Require asking before running the complete test suite. - Keep `just fmt` always allowed without approval.
55 lines
4.5 KiB
Markdown
55 lines
4.5 KiB
Markdown
# Rust/codex-rs
|
||
|
||
In the codex-rs folder where the rust code lives:
|
||
|
||
- Crate names are prefixed with `codex-`. For example, the `core` folder's crate is named `codex-core`
|
||
- When using format! and you can inline variables into {}, always do that.
|
||
- Never add or modify any code related to `CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR` or `CODEX_SANDBOX_ENV_VAR`.
|
||
- You operate in a sandbox where `CODEX_SANDBOX_NETWORK_DISABLED=1` will be set whenever you use the `shell` tool. Any existing code that uses `CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR` was authored with this fact in mind. It is often used to early exit out of tests that the author knew you would not be able to run given your sandbox limitations.
|
||
- Similarly, when you spawn a process using Seatbelt (`/usr/bin/sandbox-exec`), `CODEX_SANDBOX=seatbelt` will be set on the child process. Integration tests that want to run Seatbelt themselves cannot be run under Seatbelt, so checks for `CODEX_SANDBOX=seatbelt` are also often used to early exit out of tests, as appropriate.
|
||
|
||
Run `just fmt` (in `codex-rs` directory) automatically after making Rust code changes; do not ask for approval to run it. Before finalizing a change to `codex-rs`, run `just fix -p <project>` (in `codex-rs` directory) to fix any linter issues in the code. Prefer scoping with `-p` to avoid slow workspace‑wide Clippy builds; only run `just fix` without `-p` if you changed shared crates. Additionally, run the tests:
|
||
1. Run the test for the specific project that was changed. For example, if changes were made in `codex-rs/tui`, run `cargo test -p codex-tui`.
|
||
2. Once those pass, if any changes were made in common, core, or protocol, run the complete test suite with `cargo test --all-features`.
|
||
When running interactively, ask the user before running `just fix` to finalize. `just fmt` does not require approval. project-specific or individual tests can be run without asking the user, but do ask the user before running the complete test suite.
|
||
|
||
## TUI style conventions
|
||
|
||
See `codex-rs/tui/styles.md`.
|
||
|
||
## TUI code conventions
|
||
|
||
- Use concise styling helpers from ratatui’s Stylize trait.
|
||
- Basic spans: use "text".into()
|
||
- Styled spans: use "text".red(), "text".green(), "text".magenta(), "text".dim(), etc.
|
||
- Prefer these over constructing styles with `Span::styled` and `Style` directly.
|
||
- Example: patch summary file lines
|
||
- Desired: vec![" └ ".into(), "M".red(), " ".dim(), "tui/src/app.rs".dim()]
|
||
|
||
### TUI Styling (ratatui)
|
||
- Prefer Stylize helpers: use "text".dim(), .bold(), .cyan(), .italic(), .underlined() instead of manual Style where possible.
|
||
- Prefer simple conversions: use "text".into() for spans and vec![…].into() for lines; when inference is ambiguous (e.g., Paragraph::new/Cell::from), use Line::from(spans) or Span::from(text).
|
||
- Computed styles: if the Style is computed at runtime, using `Span::styled` is OK (`Span::from(text).set_style(style)` is also acceptable).
|
||
- Avoid hardcoded white: do not use `.white()`; prefer the default foreground (no color).
|
||
- Chaining: combine helpers by chaining for readability (e.g., url.cyan().underlined()).
|
||
- Single items: prefer "text".into(); use Line::from(text) or Span::from(text) only when the target type isn’t obvious from context, or when using .into() would require extra type annotations.
|
||
- Building lines: use vec![…].into() to construct a Line when the target type is obvious and no extra type annotations are needed; otherwise use Line::from(vec![…]).
|
||
- Avoid churn: don’t refactor between equivalent forms (Span::styled ↔ set_style, Line::from ↔ .into()) without a clear readability or functional gain; follow file‑local conventions and do not introduce type annotations solely to satisfy .into().
|
||
- Compactness: prefer the form that stays on one line after rustfmt; if only one of Line::from(vec![…]) or vec![…].into() avoids wrapping, choose that. If both wrap, pick the one with fewer wrapped lines.
|
||
|
||
## Snapshot tests
|
||
|
||
This repo uses snapshot tests (via `insta`), especially in `codex-rs/tui`, to validate rendered output. When UI or text output changes intentionally, update the snapshots as follows:
|
||
|
||
- Run tests to generate any updated snapshots:
|
||
- `cargo test -p codex-tui`
|
||
- Check what’s pending:
|
||
- `cargo insta pending-snapshots -p codex-tui`
|
||
- Review changes by reading the generated `*.snap.new` files directly in the repo, or preview a specific file:
|
||
- `cargo insta show -p codex-tui path/to/file.snap.new`
|
||
- Only if you intend to accept all new snapshots in this crate, run:
|
||
- `cargo insta accept -p codex-tui`
|
||
|
||
If you don’t have the tool:
|
||
- `cargo install cargo-insta`
|