Skip to main content

Crate rinkaku_tui

Crate rinkaku_tui 

Source
Expand description

rinkaku’s interactive terminal UI (ADR 0015/0016).

Two layers, kept deliberately separate:

  • View-models (tree, nav, order, detail, app, row_view): plain data and pure functions/state machines derived from rinkaku_core::render::Report. tree/nav/order/detail carry no ratatui/crossterm types at all (ADR 0016 decision 3). app and row_view are the stage B additions that compose those view-models into one navigable state machine and format its rows — row_view uses ratatui::text/style types (Line/Span/Style), which are plain, comparable data rather than a live Frame/ Terminal, so building one from a row stays a pure, unit-testable transformation. app stays entirely free of ratatui/crossterm types, translating real key events at the boundary instead (see run’s event loop).
  • Terminal adapter (ui, source, run): draws App’s state with ratatui, reads source files for the drill-down view, and owns the terminal lifecycle (raw mode, alternate screen, the event loop). This is the only layer that performs IO or holds a live Terminal. [event_loop::run_app]’s own event loop delegates responsibilities to sibling modules (ADR 0028, split out once this crate’s event-loop code grew past the file-size threshold): input_translate (raw crossterm events → app::InputKey) and review_flow (ADR 0048’s review-annotations composing/exporting/caching glue).

run is the crate’s single public entry point for the CLI binary: rinkaku’s main.rs hands it a rinkaku_core::render::Report once --tui is passed, in place of rendering Markdown/JSON. It also hands in the raw unified diff text main.rs already has in hand for every input mode (stdin / --base / --pr) — TUI iteration 2’s diff pane (d/D, crate::diff_view) slices hunks straight out of that same string rather than reconstructing a diff from Report (which no longer carries hunk text once extraction has run).

Modules§

annotation_markers
Derived, read-only annotation-location markers (ADR 0048’s Rendering boundary decision): a side table the tree pane and diff pane consult to badge/mark a row or line that already has an annotation attached, mirroring blast_radius_selection/diff_pane_content’s own cache-on-change precedent in crate::lib::run_app — build_annotation_markers must never be called from inside crate::ui::draw/row_view/the diff pane’s line-rendering functions, only from run_app, gated by [should_recompute_annotation_markers].
app
Interactive application state (stage B, ADR 0015/0016): composes the stage-A view-models (crate::tree, crate::nav, crate::order, crate::detail) into one state machine driven by user key input.
blast_radius
Blast-radius view-model (ADR 0019 for the re-rooting algorithm, ADR 0023 for the “blast radius” naming): given a directory or file path, builds the entry-tree text the right pane shows when the user presses R on that row — the interactive equivalent of rinkaku --entry <path>’s Markdown “Change graph”/“Repository graph” section, flattened into plain BlastRadiusLines instead of Markdown text since the pane draws with ratatui, not a Markdown renderer.
detail
Detail-pane view-model (ADR 0015): given a selected symbol, produces the plain data a detail pane shows — signature (old/new when the contract changed), classification, who depends on it (“used by”), and a pivot to callers/callees for call-graph reading order (ADR 0008’s tree, reached on demand rather than as the entry view’s spine).
diff_shape
Diff-pane content shaping (ADR 0020, ADR 0027, ADR 0030, ADR 0072, ADR 0074): given the row currently selected in the entry view (a symbol or a file) plus the already-parsed diff hunks (crate::diff_view), decides what the diff pane shows. Per ADR 0072 both symbol-row and file-row selections show the same content — the whole file’s hunks, in original git diff order, with no per-symbol grouping; a symbol selection only changes where the pane auto-scrolls to (scroll_target_line_for_symbol). ADR 0030 adds the mirror image — symbol_id_for_scroll_line resolves a scroll offset back to the symbol owning the row at that offset, so crate::run_app can sync the tree cursor when the reviewer scrolls the pane manually.
diff_view
Raw unified-diff hunk view-model (TUI iteration 2, “diff” pane): given the raw diff text main.rs already has in hand for every input mode (stdin / --base / --pr — all three end up with a String of diff text before rinkaku_core::pipeline::analyze_diff consumes it), slices it into per-file hunks with styled lines, so a reviewer can see what changed in the lines under a selected symbol/file, not just the post-change signature.
help
The ? help overlay’s content (ADR 0020, glossary wording per ADR 0023): a keymap plus a short glossary, assembled as plain data so crate::ui only has to lay it out, not decide what belongs in it.
highlight
Syntax highlighting for the diff pane (ADR 0018).
locale
The ? help overlay’s locale (ADR 0055): which language its prose renders in. Detection follows POSIX’s LC_ALL > LC_MESSAGES > LANG precedence, but only as far as this project’s actual need — a binary choice between English and Japanese — so detect_locale takes already-read env values and returns a Locale, with the real std::env::var reads left to rinkaku’s main.rs composition root (this crate’s own pure/IO split, lib.rs’s module doc comment).
nav
Navigation state machine over a flattened, visible view of a crate::tree::Tree (ADR 0015/0016): cursor movement, expand/collapse, and a stable mapping from the cursor back to the underlying node so a future detail pane knows what is selected.
order
Entry-view ordering (ADR 0016 decision 4): [rank] computes each directory’s position in the production dependency order, [sort] applies that order (or plain A-Z) to a crate::tree::Tree.
review
Review annotations (ADR 0048): a location-anchored Annotation primitive plus a pure state machine (ReviewState) for composing, listing, and exporting them, decoupled from the rest of the TUI through the narrow SelectionSnapshot input and the Vec<Annotation>/rendered-String output (this module’s own “own state, narrow input” boundary — see the ADR’s Module boundary decision).
row_view
Pure formatting of one entry-view row into styled ratatui text (stage B, ADR 0015/0016): given a crate::nav::Row (already resolved against the tree/collapse state) plus its display label, produces the ratatui::text::Line that crate::ui draws for it.
search
Vim-like search in the Source view (ADR 0057): a pure state machine (SearchState) for composing a query and stepping through its matches, decoupled from crate::ui the same way crate::review::ReviewState (ADR 0048) is decoupled from the rest of the TUI — App holds exactly one field of it, every transition lives on SearchState itself.
source
Source drill-down (ADR 0015): given a selected symbol, reads its file from disk and computes which lines to show, scrolled to and highlighting the symbol’s own range.
source_diff
Overlays a file’s diff hunks onto its full-file source view (ADR 0046), reusing crate::diff_view’s already-parsed Hunks rather than re-diffing or growing the diff pane’s own hunk-relative coordinate space (ADR 0046’s Context section explains why the diff pane itself was rejected as the home for this).
source_split
Reconstructs a file’s old-side text and pairs it against the new side into split (side-by-side) rows for the source view’s diff overlay (ADR 0049), reusing crate::split_pairing::pair_hunk_lines’s changed-run alignment rather than a second algorithm — see that ADR’s Decision 1-2 for why old-side reconstruction is a pure reverse-application over already-parsed FileHunks rather than a second IO read.
splash
The startup splash screen (ADR 0033): the rinkaku logo plus the current analysis phase, shown while main.rs runs the pre-render pipeline synchronously on the same thread that already owns the terminal — see crate::TuiSession for how a caller drives this alongside the pipeline.
stack
Stacked-PR session state (ADR 0075): the ordered layer list with a cursor (StackPosition) and the shared cache the rinkaku binary’s background analysis thread fills while the reviewer reads the current layer (PrAnalysisCache). Data and synchronisation only — no git/gh knowledge lives in this crate.
tips
One fixed usecase tip shown on the splash screen (ADR 0077), picked once per run and held for its whole duration — never rotated, to stay consistent with ADR 0033 decision 3’s “no fake progress” stance: a tip that changed every few seconds would itself read as simulated motion.
tree
Directory tree view-model (ADR 0015): the TUI’s entry view is the directory tree of changed files, not the call-graph tree — nesting depth conveys architecture, and each row carries aggregate badges.
ui
ratatui rendering (stage B, ADR 0015/0016): draws one frame from the current App state. This is the crate’s thin adapter layer — layout decisions live here, but every value drawn (row text/style, detail fields, source lines) comes from a pure view-model computed elsewhere (crate::app, crate::row_view, crate::detail, crate::source).

Structs§

ReviewPorts
Review-annotations export wiring (ADR 0048), assembled once by main.rs’s composition root and threaded through unchanged from crate::session::TuiSession::run to [run_app]: pr_context/ submitter are both Some/None together (sink A’s own “absent when no PR context” rule — crate::app::App::with_review_sink_a_available’s own doc comment), clipboard is always present since sink B never depends on a PR. browser (ADR 0050) is likewise always present — w is a global key regardless of pr_context, so the port itself always exists; only the PrContext it needs to build a URL may be absent.
TuiSession
Owns the terminal’s raw-mode/alternate-screen/mouse-capture lifecycle (ADR 0033), split out of what used to be a single run call so main.rs can draw splash::SplashState frames on the same terminal while the pre-render analysis pipeline runs synchronously, before handing off to the full event loop — without tearing down and re-entering the alternate screen in between, which would flash the terminal and defeat the splash screen’s own purpose.

Functions§

run
Runs the interactive TUI over report until the user quits, taking over the terminal for the duration of the call (raw mode + alternate screen via ratatui::try_init, restored on return and on panic — ratatui::try_init’s own panic hook covers the latter, so a bug in this crate cannot leave the caller’s terminal in raw mode).