rskit_cli/live/

renderer.rs

//! [`LiveConsole`] — a multi-region live terminal renderer.
//!
//! Renders several concurrent output streams as fixed-height "tiles" stacked in
//! a live area at the bottom of the terminal, each showing a bounded virtual
//! terminal of one stream (via [`RegionScreen`]). The tiles are an ephemeral
//! progress peek: rows that scroll off the top are dropped from the live view,
//! not flushed to scrollback, so a chatty stream does not flood the transcript.
//! Durable signal is emitted only at [`finish`](LiveConsole::finish) time — a
//! one-line verdict — and, for a failed region, a bounded replay of its retained
//! tail via [`finish_with_replay`](LiveConsole::finish_with_replay).
//!
//! The terminal mechanics (cursor positioning, redraw rate-limiting, width
//! handling, resize) are delegated to `indicatif`'s multi-progress engine, so
//! this type only owns the tile layout, the bounded failure ring, and the
//! verdict flush. It is generic: callers feed labeled byte streams and get
//! terminal rendering out, with no domain types involved.

use std::collections::HashMap;
use std::collections::VecDeque;

use indicatif::{MultiProgress, ProgressBar, ProgressDrawTarget, ProgressStyle};

use super::screen::RegionScreen;

/// The string each tile indents its content by, beneath the region header. The
/// virtual terminal grid is sized to the tile width minus this indent's width
/// so a child's output fills the visible content area exactly, without being
/// chopped.
const TILE_INDENT: &str = "  ";

/// How the live console lays out and truncates tiles.
///
/// The console does not auto-detect the terminal width or react to resizes:
/// `cols` is a fixed tile width the caller supplies once. Passing a value that
/// does not match the real terminal only over- or under-truncates the tiles; it
/// never corrupts output, since every tile line is clamped to `cols`.
#[derive(Debug, Clone, Copy)]
pub struct LiveConfig {
    /// Maximum content rows a region tile may occupy — the height of its virtual
    /// terminal and the cap a tile grows to. A tile does not reserve this height:
    /// it starts at just its header and grows with its content up to this many
    /// rows (see [`LiveConsole::feed`]), so a silent or short-lived region stays
    /// small instead of padding out a tall empty block.
    pub rows: usize,
    /// Terminal columns: the tile width. A child's output is applied to a grid
    /// sized to the visible content area (this width minus the content indent),
    /// so a real width must be passed (unlike the old truncation width, `0` is
    /// not "disable").
    pub cols: usize,
    /// How many rows that scroll off a tile are retained per region for a
    /// failure replay. The live tile stays a bounded peek; on failure this many
    /// of the most-recent scrolled-off rows (plus the final on-screen rows) are
    /// flushed to scrollback as the failure block. `0` retains nothing, so a
    /// failure replays only the rows still on screen.
    pub scrollback: usize,
}

impl Default for LiveConfig {
    fn default() -> Self {
        Self {
            rows: 5,
            cols: 80,
            scrollback: 200,
        }
    }
}

impl LiveConfig {
    /// The inner virtual-terminal grid width: the tile width minus the content
    /// indent rendered under each region header.
    ///
    /// A child whose output is fed to the tile must be told its terminal is this
    /// wide (not the full tile width), so its own line wrapping matches the grid.
    /// Otherwise a full-width in-place progress redraw wraps at the grid edge,
    /// scrolls the short grid, and churns the retained failure tail with stale
    /// half-frames on every tick — which then surface in the bounded replay when
    /// a region fails.
    #[must_use]
    pub fn content_cols(&self) -> usize {
        self.cols.saturating_sub(TILE_INDENT.len()).max(1)
    }
}

/// One in-flight region: its virtual terminal, label, backing progress line,
/// and a bounded ring of the rows that have scrolled off its tile — kept only
/// so a failure can replay recent context.
struct Region {
    bar: ProgressBar,
    screen: RegionScreen,
    label: String,
    retained: VecDeque<String>,
    /// The tallest content the tile has shown so far, capped at the grid height.
    /// The tile is rendered to this many rows so it grows with output but never
    /// shrinks mid-run — output that clears (an in-place progress redraw) leaves
    /// the tile at its high-water height rather than collapsing and reflowing.
    high_water: usize,
}

/// A live, multi-region terminal renderer.
///
/// Lifecycle per region: [`begin`](Self::begin) with a label,
/// [`feed`](Self::feed) raw bytes as they arrive, then [`finish`](Self::finish)
/// with a one-line verdict. [`set_header`](Self::set_header) updates a status
/// line pinned above the tiles.
pub struct LiveConsole {
    multi: MultiProgress,
    header: ProgressBar,
    regions: HashMap<String, Region>,
    config: LiveConfig,
}

impl LiveConsole {
    /// Create a console that renders to stderr.
    ///
    /// stderr keeps the live UI off stdout, leaving any machine-readable stream
    /// there uncorrupted.
    #[must_use]
    pub fn to_stderr(config: LiveConfig) -> Self {
        Self::with_target(ProgressDrawTarget::stderr(), config)
    }

    /// Create a console whose output is discarded — for tests and non-terminal
    /// runs where the live area must not render.
    #[must_use]
    pub fn hidden(config: LiveConfig) -> Self {
        Self::with_target(ProgressDrawTarget::hidden(), config)
    }

    fn with_target(target: ProgressDrawTarget, mut config: LiveConfig) -> Self {
        // Keep the grid and the renderer consistent: a tile always shows at
        // least one content row and its virtual terminal needs a real width.
        config.rows = config.rows.max(1);
        config.cols = config.cols.max(1);
        let multi = MultiProgress::with_draw_target(target);
        let header = multi.add(ProgressBar::new(0));
        header.set_style(message_style());
        Self {
            multi,
            header,
            regions: HashMap::new(),
            config,
        }
    }

    /// The virtual terminal grid width: the tile width minus the content
    /// indent, so a child fills the visible content area without being chopped.
    /// Children feeding a tile should be sized to this; see
    /// [`LiveConfig::content_cols`].
    #[must_use]
    pub fn content_cols(&self) -> usize {
        self.config.content_cols()
    }

    /// Set the status line shown above the tiles.
    pub fn set_header(&self, text: impl Into<String>) {
        self.header.set_message(text.into());
    }

    /// Start a new region tile labeled `label`, keyed by `id`.
    ///
    /// A duplicate `id` discards the existing region first — dropping its tile
    /// and retained tail — so a re-used key neither leaks a stale tile nor
    /// double-reports.
    pub fn begin(&mut self, id: impl Into<String>, label: impl Into<String>) {
        let id = id.into();
        let label = label.into();
        if let Some(old) = self.regions.remove(&id) {
            old.bar.finish_and_clear();
            self.multi.remove(&old.bar);
        }
        let bar = self.multi.add(ProgressBar::new(0));
        bar.set_style(message_style());
        let region = Region {
            bar,
            screen: RegionScreen::new(self.config.rows, self.content_cols()),
            label,
            retained: VecDeque::new(),
            high_water: 0,
        };
        // A fresh region shows only its header: it grows to fit content as bytes
        // arrive, so a silent or instantly-finishing unit never paints a tall
        // block of blank rows.
        region.bar.set_message(render_tile(
            &region.label,
            &[] as &[&str],
            self.config.cols,
            0,
        ));
        self.regions.insert(id, region);
    }

    /// Feed raw output bytes to region `id`, updating its tile.
    ///
    /// Rows evicted from the tile are dropped from the live view but appended to
    /// the region's bounded retention ring, so a later failure can replay recent
    /// context. A feed for an unknown `id` is ignored, so late output after a
    /// finish cannot panic.
    pub fn feed(&mut self, id: &str, bytes: &[u8]) {
        let scrollback = self.config.scrollback;
        let Some(region) = self.regions.get_mut(id) else {
            return;
        };
        for line in region.screen.feed(bytes) {
            region.retained.push_back(line);
            while region.retained.len() > scrollback {
                region.retained.pop_front();
            }
        }
        let visible = region.screen.render();
        // Grow the tile to the tallest content it has shown, capped at the grid
        // height, and render exactly that many rows. `high_water` only rises, so
        // an in-place redraw that momentarily clears rows does not shrink the
        // tile and reflow the live area.
        let filled = content_height(&visible);
        region.high_water = region.high_water.max(filled).min(self.config.rows);
        region.bar.set_message(render_tile(
            &region.label,
            &visible,
            self.config.cols,
            region.high_water,
        ));
    }

    /// Finish region `id`, removing its tile and printing `verdict` as the only
    /// scrollback line — the collapsed signal for a succeeding unit.
    ///
    /// The region's peeked output is discarded, not flushed: on success the
    /// verdict (which the caller may enrich with a run summary) is the whole
    /// story. A finish for an unknown `id` prints only the verdict. Returns any
    /// I/O error from the verdict write.
    pub fn finish(&mut self, id: &str, verdict: impl AsRef<str>) -> std::io::Result<()> {
        if let Some(region) = self.regions.remove(id) {
            region.bar.finish_and_clear();
            self.multi.remove(&region.bar);
        }
        self.multi.println(verdict.as_ref())
    }

    /// Finish a failed region `id`, replaying its retained tail to scrollback as
    /// one contiguous, label-prefixed block, then printing `verdict`.
    ///
    /// The replay is the region's retention ring (rows that scrolled off the
    /// tile, oldest first) followed by the rows still on screen — a bounded,
    /// un-interleaved failure transcript. It is returned (un-prefixed, in order)
    /// so the caller can also retain it for an end-of-run failure epilogue. A
    /// finish for an unknown `id` prints only the verdict and returns an empty
    /// body. Returns any I/O error from the flush or verdict write.
    pub fn finish_with_replay(
        &mut self,
        id: &str,
        verdict: impl AsRef<str>,
    ) -> std::io::Result<Vec<String>> {
        let mut body = Vec::new();
        if let Some(region) = self.regions.remove(id) {
            let Region {
                bar,
                screen,
                label,
                retained,
                high_water: _,
            } = region;
            for line in replay_body(&retained, screen.drain()) {
                let prefixed = scrollback_line(&label, &line);
                self.multi.println(truncate(&prefixed, self.config.cols))?;
                body.push(line);
            }
            bar.finish_and_clear();
            self.multi.remove(&bar);
        }
        self.multi.println(verdict.as_ref())?;
        Ok(body)
    }

    /// Print `line` to scrollback above the live area, without touching any tile.
    ///
    /// For output that is not tied to a live region — a header banner, or a
    /// completed unit's buffered block on the rare path where a unit is not
    /// live-tailed. Returns any I/O error from the write.
    pub fn note(&self, line: impl AsRef<str>) -> std::io::Result<()> {
        self.multi.println(line.as_ref())
    }

    /// Drop every remaining region, then clear the live area and blank the
    /// header, leaving the console reusable.
    ///
    /// Remaining regions are units that never finished; their peeked output is
    /// discarded (durable signal is emitted at finish time). Returns any I/O
    /// error from the terminal clear.
    pub fn clear(&mut self) -> std::io::Result<()> {
        for (_, region) in self.regions.drain() {
            region.bar.finish_and_clear();
            self.multi.remove(&region.bar);
        }
        self.header.set_message("");
        self.multi.clear()
    }

    /// The rows a region has retained for a failure replay (oldest first).
    #[cfg(test)]
    fn retained(&self, id: &str) -> Option<Vec<String>> {
        self.regions
            .get(id)
            .map(|region| region.retained.iter().cloned().collect())
    }

    /// The rendered height of a region's tile in lines: its header plus the
    /// current high-water content rows.
    #[cfg(test)]
    fn tile_height(&self, id: &str) -> Option<usize> {
        self.regions.get(id).map(|region| region.high_water + 1)
    }
}

/// A bar style that renders only its message (no bar, timer, or spinner).
fn message_style() -> ProgressStyle {
    ProgressStyle::with_template("{msg}").unwrap_or_else(|_| ProgressStyle::default_spinner())
}

/// The number of rows up to and including the last non-blank one — the height a
/// tile must render to show all its current content. Trailing blank grid rows
/// are excluded so a tile grows only to the content it actually holds.
fn content_height<S: AsRef<str>>(lines: &[S]) -> usize {
    lines
        .iter()
        .rposition(|line| !line.as_ref().is_empty())
        .map_or(0, |index| index + 1)
}

/// Render one tile as a labeled header line plus exactly `rows` indented
/// content lines (padded with blanks), each truncated to `cols` display
/// columns. As with [`truncate`], `cols == 0` disables truncation (used only by
/// tests; the live console always resolves `cols` to at least 1). `rows` is the
/// caller's chosen tile height (its content high-water mark), so the tile is
/// exactly as tall as the content it currently holds rather than a fixed block.
fn render_tile<S: AsRef<str>>(label: &str, lines: &[S], cols: usize, rows: usize) -> String {
    let header = format!("{}", console::style(format!("• {label}")).bold());
    let mut out = truncate(&header, cols);
    for index in 0..rows {
        out.push('\n');
        let line = lines.get(index).map_or("", AsRef::as_ref);
        out.push_str(&truncate(&format!("{TILE_INDENT}{line}"), cols));
    }
    out
}

/// Prefix a scrolled-out line with its region label for scrollback attribution.
fn scrollback_line(label: &str, line: &str) -> String {
    format!("{} {line}", console::style(format!("{label} │")).dim())
}

/// Build a failed region's replay body: its retained scrolled-off rows (oldest
/// first) followed by the rows still on screen, with trailing blank rows
/// trimmed. The caller label-prefixes each line for scrollback attribution.
fn replay_body(retained: &VecDeque<String>, on_screen: Vec<String>) -> Vec<String> {
    let mut lines: Vec<String> = retained.iter().cloned().collect();
    lines.extend(on_screen);
    while lines.last().is_some_and(String::is_empty) {
        lines.pop();
    }
    lines
}

/// Truncate `line` to `width` display columns (ANSI- and width-aware), leaving
/// it untouched when `width` is `0`.
fn truncate(line: &str, width: usize) -> String {
    if width == 0 {
        return line.to_string();
    }
    console::truncate_str(line, width, "…").into_owned()
}

#[cfg(test)]
mod tests {
    use std::collections::VecDeque;

    use super::{LiveConfig, LiveConsole, render_tile, replay_body, scrollback_line, truncate};

    fn config(rows: usize, cols: usize) -> LiveConfig {
        LiveConfig {
            rows,
            cols,
            ..LiveConfig::default()
        }
    }

    #[test]
    fn content_cols_reserves_the_indent_and_never_underflows() {
        assert_eq!(config(6, 80).content_cols(), 78);
        // Degenerate widths clamp to a usable grid rather than underflowing.
        assert_eq!(config(6, 1).content_cols(), 1);
        assert_eq!(config(6, 0).content_cols(), 1);
    }

    #[test]
    fn drives_full_region_lifecycle_without_panicking() -> std::io::Result<()> {
        let mut console = LiveConsole::hidden(config(2, 40));
        console.set_header("wave 1/2 · running 1");
        console.begin("u1", "rust:core#test");
        console.feed("u1", b"compiling\r\n");
        console.feed("u1", b"running 3 tests\r\nok\r\nok\r\n");
        console.finish("u1", "ok rust:core#test")?;
        console.clear()
    }

    #[test]
    fn reused_id_replaces_region_without_leaking() -> std::io::Result<()> {
        let mut console = LiveConsole::hidden(LiveConfig::default());
        console.begin("u1", "first");
        console.feed("u1", b"old\n");
        console.begin("u1", "second");
        console.feed("u1", b"new\n");
        console.finish("u1", "ok")
    }

    #[test]
    fn console_is_reusable_after_clear() -> std::io::Result<()> {
        let mut console = LiveConsole::hidden(LiveConfig::default());
        console.set_header("first pass");
        console.begin("u1", "task");
        console.feed("u1", b"partial output\n");
        console.clear()?;
        console.set_header("second pass");
        console.begin("u1", "task");
        console.feed("u1", b"more\n");
        console.finish("u1", "ok")
    }

    #[test]
    fn zero_rows_still_renders_content() -> std::io::Result<()> {
        let mut console = LiveConsole::hidden(config(0, 40));
        console.begin("u1", "task");
        console.feed("u1", b"visible line\r\n");
        console.finish("u1", "ok")
    }

    #[test]
    fn feed_and_finish_for_unknown_region_are_ignored() -> std::io::Result<()> {
        let mut console = LiveConsole::hidden(LiveConfig::default());
        console.feed("ghost", b"noise\n");
        console.finish("ghost", "done")
    }

    #[test]
    fn note_prints_to_scrollback_without_a_region() -> std::io::Result<()> {
        let console = LiveConsole::hidden(LiveConfig::default());
        console.note("standalone line")
    }

    #[test]
    fn scrolled_rows_are_retained_for_replay_not_lost() {
        let mut console = LiveConsole::hidden(LiveConfig {
            rows: 2,
            cols: 20,
            scrollback: 200,
        });
        console.begin("u1", "task");
        console.feed("u1", b"l1\nl2\nl3\nl4\n");
        // Only the last row stays on screen; the earlier rows scrolled off but
        // are retained for a possible failure replay.
        assert_eq!(
            console.retained("u1"),
            Some(vec!["l1".into(), "l2".into(), "l3".into()])
        );
    }

    #[test]
    fn retention_ring_is_bounded_under_a_long_feed() {
        let mut console = LiveConsole::hidden(LiveConfig {
            rows: 2,
            cols: 20,
            scrollback: 3,
        });
        console.begin("u1", "task");
        for _ in 0..50 {
            console.feed("u1", b"line\n");
        }
        assert!(console.retained("u1").is_some_and(|rows| rows.len() <= 3));
    }

    #[test]
    fn replay_body_orders_retained_then_on_screen_and_trims_blanks() {
        let retained = VecDeque::from(vec!["a".to_string(), "b".to_string()]);
        let on_screen = vec!["c".to_string(), "d".to_string(), String::new()];
        assert_eq!(replay_body(&retained, on_screen), vec!["a", "b", "c", "d"]);
    }

    #[test]
    fn failure_replay_and_success_finish_both_drop_the_region() -> std::io::Result<()> {
        let mut console = LiveConsole::hidden(config(2, 20));
        console.begin("ok", "task");
        console.feed("ok", b"noise\n");
        console.finish("ok", "ok task")?;
        assert!(console.retained("ok").is_none());

        console.begin("bad", "task");
        console.feed("bad", b"panic!\n");
        console.finish_with_replay("bad", "failed task")?;
        assert!(console.retained("bad").is_none());
        Ok(())
    }

    #[test]
    fn finish_with_replay_returns_the_transcript_for_an_end_of_run_epilogue() -> std::io::Result<()>
    {
        let mut console = LiveConsole::hidden(config(2, 20));
        console.begin("bad", "task");
        console.feed("bad", b"line one\nline two\n");
        // The replayed body is returned un-prefixed and in order so a caller can
        // retain it and re-surface all failures together after the run.
        let body = console.finish_with_replay("bad", "failed task")?;
        assert_eq!(body, vec!["line one".to_string(), "line two".to_string()]);
        Ok(())
    }

    #[test]
    fn finish_with_replay_for_an_unknown_region_returns_an_empty_body() -> std::io::Result<()> {
        let mut console = LiveConsole::hidden(config(2, 20));
        let body = console.finish_with_replay("ghost", "failed")?;
        assert!(body.is_empty());
        Ok(())
    }

    #[test]
    fn render_tile_labels_and_indents_lines() {
        let tile = render_tile("core", &["a", "b"], 0, 2);
        let stripped = console::strip_ansi_codes(&tile);
        assert_eq!(stripped, "• core\n  a\n  b");
    }

    #[test]
    fn content_height_counts_up_to_the_last_non_blank_row() {
        assert_eq!(super::content_height::<&str>(&[]), 0);
        assert_eq!(super::content_height(&["", "", ""]), 0);
        assert_eq!(super::content_height(&["a", "", ""]), 1);
        assert_eq!(super::content_height(&["a", "", "b", ""]), 3);
    }

    #[test]
    fn a_silent_region_renders_only_its_header() {
        let mut console = LiveConsole::hidden(config(12, 40));
        console.begin("u1", "rust:core#test");
        // Nothing fed yet: the tile is a single header line, not a block of
        // reserved blank rows.
        assert_eq!(console.tile_height("u1"), Some(1));
    }

    #[test]
    fn a_tile_grows_with_content_up_to_the_cap() {
        let mut console = LiveConsole::hidden(config(3, 40));
        console.begin("u1", "task");
        console.feed("u1", b"one\n");
        // header + one content row.
        assert_eq!(console.tile_height("u1"), Some(2));
        console.feed("u1", b"two\nthree\nfour\nfive");
        // Capped at the grid height (3 content rows) + header.
        assert_eq!(console.tile_height("u1"), Some(4));
    }

    #[test]
    fn a_grown_tile_does_not_shrink_when_output_clears() {
        let mut console = LiveConsole::hidden(config(3, 40));
        console.begin("u1", "task");
        console.feed("u1", b"a\r\nb\r\nc");
        assert_eq!(console.tile_height("u1"), Some(4));
        // An in-place redraw that collapses to a single line keeps the tile at
        // its high-water height instead of reflowing the live area.
        console.feed("u1", b"\x1b[H\x1b[2Jshort");
        assert_eq!(console.tile_height("u1"), Some(4));
    }

    #[test]
    fn render_tile_pads_to_fixed_height() {
        let tile = render_tile("core", &["only"], 0, 3);
        let stripped = console::strip_ansi_codes(&tile);
        assert_eq!(stripped, "• core\n  only\n  \n  ");
    }

    #[test]
    fn render_tile_truncates_header_and_content_to_width() {
        let tile = render_tile("a-very-long-label", &["a-very-long-content-line"], 8, 1);
        for line in console::strip_ansi_codes(&tile).lines() {
            assert!(console::measure_text_width(line) <= 8);
        }
    }

    #[test]
    fn scrollback_line_prefixes_with_label() {
        let line = scrollback_line("core", "hello");
        let stripped = console::strip_ansi_codes(&line);
        assert_eq!(stripped, "core │ hello");
    }

    #[test]
    fn replay_line_clamped_to_width_never_wraps() {
        // A content row is sized to the tile's content area, but the scrollback
        // replay prefixes it with the full unit label — the composed line must be
        // clamped to the console width so it never wraps into an orphan fragment.
        let content = "x".repeat(200);
        let composed = scrollback_line("rust@rust:core#test", &content);
        let clamped = truncate(&composed, 140);
        assert!(console::measure_text_width(&clamped) <= 140);
    }

    #[test]
    fn truncate_respects_width_and_passthrough() {
        assert_eq!(truncate("hello world", 0), "hello world");
        let cut = truncate("hello world", 5);
        assert!(console::measure_text_width(&cut) <= 5);
    }
}