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 fromrinkaku_core::render::Report.tree/nav/order/detailcarry noratatui/crosstermtypes at all (ADR 0016 decision 3).appandrow_vieware the stage B additions that compose those view-models into one navigable state machine and format its rows —row_viewusesratatui::text/styletypes (Line/Span/Style), which are plain, comparable data rather than a liveFrame/Terminal, so building one from a row stays a pure, unit-testable transformation.appstays entirely free ofratatui/crosstermtypes, translating real key events at the boundary instead (seerun’s event loop). - Terminal adapter (
ui,source,run): drawsApp’s state withratatui, 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 liveTerminal. [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(rawcrosstermevents →app::InputKey) andreview_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 incrate::lib::run_app—build_annotation_markersmust never be called from insidecrate::ui::draw/row_view/the diff pane’s line-rendering functions, only fromrun_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
Ron that row — the interactive equivalent ofrinkaku --entry <path>’s Markdown “Change graph”/“Repository graph” section, flattened into plainBlastRadiusLines instead of Markdown text since the pane draws withratatui, 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 originalgit difforder, 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_lineresolves a scroll offset back to the symbol owning the row at that offset, socrate::run_appcan 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.rsalready has in hand for every input mode (stdin /--base/--pr— all three end up with aStringof diff text beforerinkaku_core::pipeline::analyze_diffconsumes 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 socrate::uionly 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’sLC_ALL > LC_MESSAGES > LANGprecedence, but only as far as this project’s actual need — a binary choice between English and Japanese — sodetect_localetakes already-read env values and returns aLocale, with the realstd::env::varreads left torinkaku’smain.rscomposition 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 acrate::tree::Tree. - review
- Review annotations (ADR 0048): a location-anchored
Annotationprimitive plus a pure state machine (ReviewState) for composing, listing, and exporting them, decoupled from the rest of the TUI through the narrowSelectionSnapshotinput and theVec<Annotation>/rendered-Stringoutput (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
ratatuitext (stage B, ADR 0015/0016): given acrate::nav::Row(already resolved against the tree/collapse state) plus its display label, produces theratatui::text::Linethatcrate::uidraws 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 fromcrate::uithe same waycrate::review::ReviewState(ADR 0048) is decoupled from the rest of the TUI —Appholds exactly one field of it, every transition lives onSearchStateitself. - 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-parsedHunks 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-parsedFileHunksrather than a second IO read. - splash
- The startup splash screen (ADR 0033): the rinkaku logo plus the current
analysis phase, shown while
main.rsruns the pre-render pipeline synchronously on the same thread that already owns the terminal — seecrate::TuiSessionfor 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 therinkakubinary’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
ratatuirendering (stage B, ADR 0015/0016): draws one frame from the currentAppstate. 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§
- Review
Ports - Review-annotations export wiring (ADR 0048), assembled once by
main.rs’s composition root and threaded through unchanged fromcrate::session::TuiSession::runto [run_app]:pr_context/submitterare bothSome/Nonetogether (sink A’s own “absent when no PR context” rule —crate::app::App::with_review_sink_a_available’s own doc comment),clipboardis always present since sink B never depends on a PR.browser(ADR 0050) is likewise always present —wis a global key regardless ofpr_context, so the port itself always exists; only thePrContextit 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
runcall somain.rscan drawsplash::SplashStateframes 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
reportuntil the user quits, taking over the terminal for the duration of the call (raw mode + alternate screen viaratatui::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).