codex/prs/bolinfest/study/PR-1810-study.md

DOs

• Bold, Exact Assertions: prefer assert_eq! over loose contains checks; use pretty diffs for failures.

  use pretty_assertions::assert_eq;
  
  assert_eq!(
      items,
      vec![ResponseItem::Message {
          id: None,
          role: "assistant".to_string(),
          content: vec![ContentItem::OutputText { text: "Hello, world!".to_string() }],
      }]
  );
  

• Merge Duplicates In History: combine adjacent assistant messages and test the exact merged result.

  // merge logic
  match (&*item, history.items.last_mut()) {
      (ResponseItem::Message { role: r1, content: c1, .. },
       Some(ResponseItem::Message { role: r2, content: c2, .. }))
          if r1 == "assistant" && r2 == "assistant" => append_text_content(c2, c1),
      _ => history.items.push(item.clone()),
  }
  

• Use Destructuring To Ignore Fields: make intent clear when final payload is unused due to streaming.

  match event {
      EventMsg::AgentMessage(AgentMessageEvent { message: _ }) => {
          self.finalize_stream(StreamKind::Answer);
      }
      _ => {}
  }
  

• Centralize Redraws And Control Flow: track whether a branch handled the update, then redraw once.

  pub fn update_status_text(&mut self, text: String) {
      let mut handled = false;
      if let Some(view) = self.active_view.as_mut() {
          handled |= matches!(view.update_status_text(text.clone()), NeedsRedraw);
      } else {
          let mut v = StatusIndicatorView::new(self.app_event_tx.clone());
          v.update_text(text.clone());
          self.active_view = Some(Box::new(v));
          self.status_view_active = true;
          handled = true;
      }
      if !handled {
          self.live_status.get_or_insert_with(|| StatusIndicatorWidget::new(self.app_event_tx.clone()))
              .update_text(text);
      }
      self.request_redraw();
  }
  

• Import Types At Top: avoid fully-qualified paths in signatures.

  use ratatui::text::Line;
  
  pub fn set_live_ring_rows(&mut self, max_rows: u16, rows: Vec<Line<'static>>) { ... }
  

• Prefer &'static str When Possible: avoid allocating String for static content.

  lines.push(ratatui::text::Line::from(""));
  

• Name Things Clearly: use descriptive names instead of one-letter variables.

  if let Some(view) = &self.active_view {
      view.render(view_rect, buf);
  }
  

• Make Test Utilities Reusable: factor repeated setup into helpers or a scenario struct.

  struct TestScenario { width: u16, height: u16, term: Terminal<TestBackend> }
  
  impl TestScenario {
      fn run_insert(&mut self, lines: Vec<Line<'static>>) -> Vec<u8> { ... }
      fn screen_rows_from_bytes(&self, bytes: &[u8]) -> Vec<String> { ... }
  }
  

• Gate Emulator Tests And Keep Them Dev-Only: put vt100 under dev-dependencies and behind a feature.

  # Cargo.toml
  [features]
  vt100-tests = []
  
  [dev-dependencies]
  vt100 = { version = "0.16.2", optional = true }
  pretty_assertions = "1"
  

• Use Writer-Based Output For Testability: separate rendering from I/O, then test via a buffer.

  pub fn insert_history_lines_to_writer<B, W>(
      term: &mut Terminal<B>,
      writer: &mut W,
      lines: Vec<Line>,
  ) where
      B: ratatui::backend::Backend,
      W: std::io::Write,
  { /* queue!(writer, ...); */ }
  

• Handle Unicode Width Correctly: wrap using display width (emoji/CJK) and provide invariance tests.

  pub fn take_prefix_by_width(text: &str, max_cols: usize) -> (String, &str, usize) { ... }
  
  let (prefix, _suffix, width) = take_prefix_by_width("😀你好", 4);
  assert_eq!(prefix, "😀"); // 😀 is width 2
  assert_eq!(width, 2);
  

• Strip ANSI Before Measuring Or Animating: prevent control bytes from corrupting rendering.

  let line = ansi_escape_line(&self.text);
  let plain = line.spans.iter().map(|s| s.content.as_ref()).collect::<String>();
  

• Be Explicit About Channel Backpressure And Logs: pick bounded vs. unbounded intentionally and log at the right level.

  // backpressure on submissions; allow bursts on events
  let (tx_sub, rx_sub) = async_channel::bounded(64);
  let (tx_event, rx_event) = async_channel::unbounded();
  
  debug!("Configuring session: model={model}; provider={provider:?}; resume={resume_path:?}");
  

• Keep UI Layout Invariants Tested: assert bottom padding behavior and overlay stacking.

  // height=2: top has status, bottom is blank padding
  assert!(row0.contains("Working"));
  assert!(row1.trim().is_empty());
  

• Clean Module Visibility For Tests: make internal modules pub where practical within the workspace (e.g., custom_terminal, insert_history, live_wrap).

DON’Ts

• Don’t Use Vague Tests: avoid assert!(contains(...)) when you can assert the exact structure or full screen state.

• Don’t Scatter request_redraw() Across Branches: avoid multiple early returns that obscure flow; consolidate redraw at the end.

• Don’t Keep Emulator Crates In Runtime Deps: keep vt100 in [dev-dependencies] and guard tests with #[cfg(feature = "vt100-tests")].

• Don’t Leave Single-Letter Identifiers: replace ov, s, etc., with clear names like view, text.

• Don’t Hardcode Fully Qualified Types In Sigs: import once at the module top.

• Don’t Allocate Strings For Literals: use &'static str where possible.

• Don’t Leave Unused Code/Events/Comments: remove unused variants (e.g., stale AppEvent), “Removed …” comments, or unclear references (e.g., “TS ref?”) without context.

• Don’t Emit Raw ANSI Into Buffers: always sanitize before measuring or rendering to avoid cursor jumps/artifacts.

• Don’t Forget To Clear Live Overlays: call clear_live_ring() and reset status_view_active when tasks complete.

• Don’t Duplicate Assistant Messages: merge adjacent assistant entries in conversation history.

• Don’t Overuse info! For Noisy Logs: prefer debug! for verbose or frequent messages.

• Don’t Handwave Backpressure: document why a channel is bounded/unbounded and choose deliberately.

• Don’t Leave Padding/Height Edge Cases Untested: small heights should gracefully shrink padding while preserving essential content.

Code Snippets Recap

• Unified status update with single redraw:

  pub fn update_status_text(&mut self, text: String) {
      let mut handled = false;
      if let Some(view) = self.active_view.as_mut() {
          handled |= matches!(view.update_status_text(text.clone()), NeedsRedraw);
      } else {
          let mut v = StatusIndicatorView::new(self.app_event_tx.clone());
          v.update_text(text.clone());
          self.active_view = Some(Box::new(v));
          self.status_view_active = true;
          handled = true;
      }
      if !handled {
          self.live_status.get_or_insert_with(|| StatusIndicatorWidget::new(self.app_event_tx.clone()))
              .update_text(text);
      }
      self.request_redraw();
  }
  

• Dev-only emulator tests gating:

  // tests/vt100_history.rs
  #![cfg(feature = "vt100-tests")]
  #![expect(clippy::expect_used)]
  
  use ratatui::backend::TestBackend;
  use ratatui::layout::Rect;
  use ratatui::text::Line;
  
  struct TestScenario { /* ... */ }
  
  #[test]
  fn hist_001_basic_insertion_no_wrap() {
      let area = Rect::new(0, 5, 20, 1);
      let mut scenario = TestScenario::new(20, 6, area);
      let buf = scenario.run_insert(vec![Line::from("first"), Line::from("second")]);
      let rows = scenario.screen_rows_from_bytes(&buf);
      assert_eq!(rows[4], "first");
      assert_eq!(rows[5], "second");
  }
  

• History merging test with exact expectation:

  let mut h = ConversationHistory::default();
  h.record_items([&assistant_msg("Hello"), &assistant_msg(", world!")]);
  assert_eq!(
      h.contents(),
      vec![ResponseItem::Message {
          id: None,
          role: "assistant".to_string(),
          content: vec![ContentItem::OutputText { text: "Hello, world!".to_string() }],
      }]
  );
  

• Writer-based insertion API usage:

  let mut out: Vec<u8> = Vec::new();
  insert_history_lines_to_writer(&mut terminal, &mut out, lines);
  // feed `out` into vt100::Parser for assertions
  

• Unicode-aware wrapping helper:

  pub fn take_prefix_by_width(text: &str, max_cols: usize) -> (String, &str, usize) {
      use unicode_width::UnicodeWidthChar;
      let mut cols = 0;
      let mut end = 0;
      for (i, ch) in text.char_indices() {
          let w = UnicodeWidthChar::width(ch).unwrap_or(0);
          if cols + w > max_cols { break; }
          cols += w;
          end = i + ch.len_utf8();
          if cols == max_cols { break; }
      }
      (text[..end].to_string(), &text[end..], cols)
  }