tuicr: Instructions file for GitHub Copilot

tuicr — Copilot Instructions

tuicr is a Rust terminal UI application for reviewing diffs (AI-generated or otherwise) like a GitHub pull request, directly from the terminal.

Build, test, lint

cargo build
cargo test
cargo fmt
cargo clippy -- -D warnings   # CI enforces -D warnings

Run a single test by name:

cargo test test_name_fragment   # matches any test whose name contains the fragment

Architecture

Central state: App (src/app.rs)

All UI state lives in App. It holds the VCS backend, the parsed diff files, the review session, scroll/cursor positions, and the current InputMode. Everything in the render and event loop reads from App.

Input flow

crossterm Event → map_key_to_action(key, InputMode) → Action enum → handler in src/handler/

Each InputMode has its own handler (handle_diff_action, handle_command_action, etc.). Actions are defined in src/input/keybindings.rs.

VCS abstraction (src/vcs/)

VcsBackend trait in src/vcs/traits.rs abstracts Git, Mercurial, and Jujutsu. detect_vcs() in src/vcs/mod.rs auto-detects (jj → git → hg). Git has two backends: libgit2 (default) and a CLI fallback used automatically for sparse checkouts, or forced via backend = "cli" in config.

DiffFormat::Hg and DiffFormat::GitStyle share the text parser in src/vcs/diff_parser.rs. Native Git uses libgit2 directly.

Forge integration (src/forge/)

ForgeBackend trait in src/forge/traits.rs. Only GitHub is implemented (v1), via the gh CLI — not a REST/GraphQL SDK. All gh invocations go through GhCommandRunner in src/forge/github/gh.rs.

Thread boundary rule: network calls happen on a background thread; diff parsing and state mutations happen on the main thread. SyntaxHighlighter is not Send. Background threads return plain Send-safe data; finish_* functions on the main thread do the parsing.

Persistence

Sessions are JSON files at ~/.local/share/tuicr/reviews/. Loaded by find_session_for_repo() on startup. Config is at ~/.config/tuicr/config.toml (XDG, or %APPDATA%\tuicr\config.toml on Windows). Unknown config keys produce startup warnings, not errors.