(6ce2c47) Mark each relation with the status of the ticket it names

The Relations block named each target and said nothing about where it was, so
the question actually asked of it, whether a blocker is finished, meant closing
the overlay and going to find the other ticket. Each row now carries a mark for
its target's status, ahead of the id, where it describes the target rather than
the row.

A rising bar, U+2581 through U+2588 for backlog to done, and ? for a target the
board no longer holds. Not a circle: the cards spend those on the priority
meter two cells from nothing at all, and another circle would be read as a
level. The ramp is also the meaning, so the shape says which status it is.

The colour could not. Every colour in the guideline already means one thing and
the eight tag slots are reserved, so four status colours could only have come
out of something else's meaning. So the shape carries the status and the colour
says only that it is one: orange, which is what Status already means, and grey
on the missing mark, beside the _missing_ that grey already spells. An
unrecognised status reads as missing rather than as a fifth stage, and
every_status_has_a_mark pins the pairing against status_dirs so a status added
later fails a test instead of quietly reading as ?.

The plain text was the real cost. Detail.text was one String drawn by a
Paragraph, deliberately uncoloured because an escape sequence there is drawn as
literal bytes, which is 6d327df. So the block cannot arrive pre-painted.
Resolved.relations is now rows, content_parts returns the body as
BodyPart::Text and BodyPart::Relations with the text painted and the rows
untouched, and the two renderers take it from there: content_trim paints the
rows into escapes, and the board styles the same cells as spans.

One builder, two painters. relation_rows decides which edges there are, what
they are called and which direction leads; relation_cells decides the layout,
the mark and the colours; paint_cells and span_of are the only things that
differ. Cell is the unit both take, the same shape the palette uses to stop a
colour existing for one renderer and not the other. reference_cells is now the
one spelling of a cross reference, shared with the Campaign field.

Detail.body is a ratatui Text and is the only thing measured, so last_offset
and the Paragraph cannot wrap the body two ways. Detail::plain() flattens it
for the suite and is cfg(test): a second representation carried beside the
spans is a second thing to disagree.

show carries the same mark, decided here rather than discovered later. The rows
are one builder so it was free, and two views disagreeing about what a relation
shows is a difference nobody can explain afterwards. That is a change to what
the CLI prints, so the minor goes on the last commit of this pair.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-22 15:20:56 +02:00
co-authored by Claude Opus 5
parent c437d87e9e
commit ece201e3ab
6 changed files with 662 additions and 105 deletions
+1 -1
View File
@@ -179,7 +179,7 @@ pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> Str
/// rather than at each call site.
pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result<Resolved> {
Ok(Resolved {
relations: relations_block(content, worklane_dir, colored)?,
relations: relations_for(content, worklane_dir)?,
campaign: campaign_cell(content, &CampaignIndex::load(worklane_dir)?, colored),
})
}
+256 -34
View File
@@ -16,7 +16,7 @@ use anyhow::{Context, Result};
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use ratatui::layout::{Constraint, Direction, Layout, Margin, Rect, Size};
use ratatui::style::{Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::text::{Line, Span, Text};
use ratatui::widgets::{Block, Borders, Clear, Paragraph, Tabs, Wrap};
use ratatui::Frame;
@@ -202,7 +202,35 @@ pub struct Detail {
/// card that said so, and the id alone is not an address across several boards:
/// acting on the ticket means knowing which project to run the command in.
pub project: Option<String>,
pub text: String,
/// The body as the overlay draws it: lines of styled spans, not a string.
///
/// Styled here rather than painted into the text, because ratatui draws an escape
/// sequence in a paragraph as literal bytes, which is 6d327df. It is also the one
/// value the clamp and the draw both measure, so neither can wrap it differently
/// from the other.
pub body: Text<'static>,
}
impl Detail {
/// The body as plain text, one line per drawn line.
///
/// Only the suite asks: it is what an assertion about the body reads, and what shows
/// that no escape sequence reached it. Nothing in the draw path needs it, so it is
/// not carried alongside the spans where the two could disagree.
#[cfg(test)]
pub fn plain(&self) -> String {
self.body
.lines
.iter()
.map(|line| {
line.spans
.iter()
.map(|span| span.content.as_ref())
.collect::<String>()
})
.collect::<Vec<String>>()
.join("\n")
}
}
/// The open search prompt: what has been typed, and whether the last enter missed.
@@ -702,7 +730,7 @@ impl Board {
let text = detail_text_area(Rect::new(0, 0, screen.width, screen.height));
// A screenful less a line, so the eye has something to land on after the jump.
let step = text.height.saturating_sub(1).max(1) as isize;
let last = last_offset(&detail.text, text) as isize;
let last = last_offset(&detail.body, text) as isize;
self.offset = (self.offset as isize + pages.saturating_mul(step)).clamp(0, last) as u16;
}
@@ -744,15 +772,73 @@ fn detail_of(card: &Card) -> Detail {
None => Vec::new(),
};
let mut out = content_trim(&content, false, &resolved);
// Colour off for the text, which is what keeps escapes out of the paragraph, and the
// relations arrive as rows so the board can style them itself.
let mut parts = content_parts(&content, false, &resolved);
parts.push(BodyPart::Text(format!(
"\n{}",
format_comments_with(&comments, false)
)));
out.push('\n');
out.push_str(&format_comments_with(&comments, false));
Detail {
title: ticket.title.clone(),
id: ticket.id.clone(),
project: card.project.clone(),
text: out,
body: detail_body(&parts),
}
}
/// The rendered body as lines of spans: the text split where it says, and each relation
/// row styled from the cells the CLI paints.
///
/// A part that does not end on a newline runs on into the next one rather than closing a
/// line, so the seam between text and relations is wherever the body actually put it and
/// not wherever a part happened to end.
fn detail_body(parts: &[BodyPart]) -> Text<'static> {
let mut lines: Vec<Line<'static>> = Vec::new();
let mut open: Vec<Span<'static>> = Vec::new();
for part in parts {
match part {
BodyPart::Text(text) => {
let mut rest = text.as_str();
while let Some((line, tail)) = rest.split_once('\n') {
if !line.is_empty() {
open.push(Span::raw(line.to_string()));
}
lines.push(Line::from(std::mem::take(&mut open)));
rest = tail;
}
if !rest.is_empty() {
open.push(Span::raw(rest.to_string()));
}
}
// One line each, from the same cells `render_relations` paints, so the block
// cannot read differently here than it does in `show`.
BodyPart::Relations(rows) => {
for row in relation_cells(rows) {
open.extend(row.into_iter().map(span_of));
lines.push(Line::from(std::mem::take(&mut open)));
}
}
}
}
if !open.is_empty() {
lines.push(Line::from(open));
}
Text::from(lines)
}
/// A cell as the board draws it: the same text in the same colour, as a span.
///
/// The other half of `paint_cells`, which is the CLI's. `From<Color>` is what makes the
/// two agree about what the colour is.
fn span_of(cell: Cell) -> Span<'static> {
match cell.color {
Some(color) => Span::styled(cell.text, Style::default().fg(color.into())),
None => Span::raw(cell.text),
}
}
@@ -1571,8 +1657,8 @@ fn detail_text_area(area: Rect) -> Rect {
/// Measured by the widget rather than counted by hand, since it wraps on words. A clamp
/// on the raw lines would stop short of the end on a wrapped ticket, and one that
/// ignored the wrapping the other way would scroll past it into blank space.
fn last_offset(detail: &str, text: Rect) -> u16 {
let wrapped = Paragraph::new(detail)
fn last_offset(detail: &Text<'static>, text: Rect) -> u16 {
let wrapped = Paragraph::new(detail.clone())
.wrap(Wrap { trim: false })
.line_count(text.width);
@@ -1586,7 +1672,7 @@ fn draw_detail(frame: &mut Frame, detail: &Detail, offset: u16, area: Rect) {
// Clamped here as well as on the keypress: the terminal may have been resized since,
// and a ticket read to its end can grow shorter under a tick.
let offset = offset.min(last_offset(&detail.text, detail_text_area(area)));
let offset = offset.min(last_offset(&detail.body, detail_text_area(area)));
let block = Block::default()
.borders(Borders::ALL)
@@ -1598,7 +1684,7 @@ fn draw_detail(frame: &mut Frame, detail: &Detail, offset: u16, area: Rect) {
frame.render_widget(Clear, overlay);
frame.render_widget(
Paragraph::new(detail.text.to_string())
Paragraph::new(detail.body.clone())
.block(block)
.wrap(Wrap { trim: false })
.scroll((offset, 0)),
@@ -2571,16 +2657,16 @@ mod tests {
board.toggle_detail();
let detail = board.detail.as_ref().expect("no detail");
assert!(detail.text.contains("A description."), "{}", detail.text);
assert!(detail.text.contains("Crit one"), "{}", detail.text);
assert!(detail.text.contains("A note from elsewhere."), "{}", detail.text);
assert!(detail.text.contains("bob"), "{}", detail.text);
assert!(detail.plain().contains("A description."), "{}", detail.plain());
assert!(detail.plain().contains("Crit one"), "{}", detail.plain());
assert!(detail.plain().contains("A note from elsewhere."), "{}", detail.plain());
assert!(detail.plain().contains("bob"), "{}", detail.plain());
// Plain text, since ratatui would print an escape as literal bytes
assert!(
!detail.text.contains('\x1b'),
!detail.plain().contains('\x1b'),
"escapes reached the detail view: {:?}",
detail.text
detail.plain()
);
board.toggle_detail();
@@ -2605,7 +2691,7 @@ mod tests {
// The heading stays out of the text: `show` prints it and here the border
// carries it, so it is on screen once rather than twice.
assert!(
!board.detail.as_ref().unwrap().text.contains("First one"),
!board.detail.as_ref().unwrap().plain().contains("First one"),
"{:?}",
board.detail
);
@@ -2670,7 +2756,7 @@ mod tests {
let mut board = one_board(&dir);
board.toggle_detail();
assert!(!board.detail.as_ref().unwrap().text.contains("A late note."));
assert!(!board.detail.as_ref().unwrap().plain().contains("A late note."));
let comments = dir.join("comments").join(uuid);
std::fs::create_dir_all(&comments).unwrap();
@@ -2682,7 +2768,7 @@ mod tests {
assert!(board.tick().unwrap(), "the tick saw no change");
assert!(
board.detail.as_ref().unwrap().text.contains("A late note."),
board.detail.as_ref().unwrap().plain().contains("A late note."),
"{:?}",
board.detail
);
@@ -2809,7 +2895,7 @@ mod tests {
// By id in the text: the heading is stripped from the body, and the title
// travels beside it for the block title instead.
assert!(
board.detail.as_ref().unwrap().text.contains("11111111"),
board.detail.as_ref().unwrap().plain().contains("11111111"),
"{:?}",
board.detail
);
@@ -2817,7 +2903,7 @@ mod tests {
board.select_card(1, SCREEN);
assert_eq!(selected_title(&board), Some("Beta".to_string()));
assert!(
board.detail.as_ref().unwrap().text.contains("22222222"),
board.detail.as_ref().unwrap().plain().contains("22222222"),
"{:?}",
board.detail
);
@@ -3299,7 +3385,7 @@ mod tests {
let mut board = one_board(&dir);
board.toggle_detail();
assert!(
board.detail.as_ref().unwrap().text.contains("11111111"),
board.detail.as_ref().unwrap().plain().contains("11111111"),
"{:?}",
board.detail
);
@@ -3310,7 +3396,7 @@ mod tests {
let detail = board.detail.as_ref().expect("the overlay closed on a jump");
assert_eq!(detail.title, "Gamma third");
assert!(detail.text.contains("33333333"), "{detail:?}");
assert!(detail.plain().contains("33333333"), "{detail:?}");
}
/// With no prompt open the keyboard belongs to the action arms, so `search_key` has
@@ -4007,9 +4093,9 @@ mod tests {
_ => "22222222",
};
assert!(
detail.text.contains(uuid),
detail.plain().contains(uuid),
"the overlay opened another project's ticket: {project} {:?}",
detail.text
detail.plain()
);
let screen = render(&board, SCREEN.width, SCREEN.height);
@@ -4020,7 +4106,7 @@ mod tests {
board.select_card(1, SCREEN);
let moved = board.detail.as_ref().expect("no detail");
assert_ne!(moved.project, Some(project), "the modal stayed on one project");
assert!(!moved.text.contains(uuid), "{:?}", moved.text);
assert!(!moved.plain().contains(uuid), "{:?}", moved.plain());
}
/// The board and the listing draw from the same palette, so a colour cannot exist
@@ -4037,6 +4123,141 @@ mod tests {
/// The style of the first cell drawing `symbol`, so a test can ask what colour a
/// glyph actually reached the screen in rather than trusting the span it was built
/// from.
fn drawn_color(
board: &Board,
width: u16,
height: u16,
symbol: char,
) -> Option<ratatui::style::Color> {
let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
terminal.draw(|frame| draw(frame, board)).unwrap();
let buffer = terminal.backend().buffer().clone();
(0..buffer.area.height)
.flat_map(|y| (0..buffer.area.width).map(move |x| (x, y)))
.find(|(x, y)| buffer[(*x, *y)].symbol() == symbol.to_string())
.map(|(x, y)| buffer[(x, y)].fg)
}
/// A board holding one relation, so the tests below have a block to look at.
///
/// The section goes where `relate` writes it, ahead of the metadata, rather than in
/// `write_ticket`'s trailer: the block has to be on screen for a test to read the
/// colour off the drawn buffer.
fn related_board() -> PathBuf {
let dir = board_dir();
let holder = "11111111-0000-4000-8000-000000000000";
let target = "22222222-0000-4000-8000-000000000000";
std::fs::write(
dir.join("backlog").join(format!("{holder}_a-holder.md")),
format!(
"# A holder\n\n## Description\nA description.\n\n## Relations\n\
- blocked by {target}\n\n## Metadata\n\n- **ID**: {holder}\n\
- **Priority**: 2\n- **Status**: backlog\n"
),
)
.unwrap();
write_ticket(&dir, "reviewing", target, "The target", "");
dir
}
/// The mark is a ratatui style, not an escape sequence in the body. Passing `true`
/// to the body renderers would put `\x1b[33m` in the paragraph and draw it as literal
/// bytes, which is 6d327df; this asserts the colour arrived and the escape did not.
#[test]
fn the_relation_mark_is_drawn_as_a_style_and_not_as_an_escape() {
let dir = related_board();
let mut board = one_board(&dir);
board.toggle_detail();
let (mark, colour) = status_mark(Some("reviewing"));
let detail = board.detail.as_ref().expect("no detail");
assert!(
detail.plain().contains(mark),
"the target's mark is not in the body: {:?}",
detail.plain()
);
assert!(
!detail.plain().contains('\x1b'),
"an escape reached the body: {:?}",
detail.plain()
);
assert_eq!(
drawn_color(&board, SCREEN.width, SCREEN.height, mark),
Some(colour.into()),
"the mark was drawn without its colour"
);
}
/// One layout, two painters. The overlay draws the block from the same cells the CLI
/// paints, so the two views cannot come to list different edges in a different order
/// or pad them differently.
#[test]
fn the_overlay_and_the_listing_draw_the_same_block() {
let dir = related_board();
let mut board = one_board(&dir);
board.toggle_detail();
let content = std::fs::read_to_string(
board.selected().expect("no selection").ticket.path.clone(),
)
.unwrap();
let rows = relations_for(&content, &dir).unwrap();
let printed = render_relations(&rows, false);
assert!(!printed.is_empty(), "the fixture has no relations");
assert!(
board.detail.as_ref().unwrap().plain().contains(printed.trim_end()),
"the overlay drew a different block than the listing prints: {printed:?}"
);
}
/// The body is no longer one string, so the clamp and the draw could measure two
/// different things. They take the same `Text`, and this is what says so: a ticket
/// whose relations run past the overlay scrolls to its last row.
#[test]
fn the_scroll_measures_the_relations_block_with_the_rest_of_the_body() {
let dir = board_dir();
let holder = "11111111-0000-4000-8000-000000000000";
let mut relations = String::from("\n## Relations\n");
for n in 0..20 {
let target = format!("2222222{n:x}-0000-4000-8000-000000000000");
relations.push_str(&format!("- blocked by {target}\n"));
write_ticket(&dir, "done", &target, &format!("Target {n:02}"), "");
}
write_ticket(&dir, "backlog", holder, "A holder", &relations);
let mut board = one_board(&dir);
board.toggle_detail();
let area = detail_text_area(Rect::new(0, 0, SCREEN.width, SCREEN.height));
let last = last_offset(&board.detail.as_ref().unwrap().body, area);
assert!(last > 0, "the fixture fits on one screen, so nothing is measured");
// Far past the end, so the clamp is what stops it.
for _ in 0..20 {
board.scroll_detail(1, SCREEN);
}
assert_eq!(board.offset, last, "the clamp and the body disagree");
// The relations sit at the end of this fixture, so the last row and the comments
// line are what the last screenful has to hold.
let screen = render(&board, SCREEN.width, SCREEN.height).join("\n");
assert!(
screen.contains("Target 19"),
"the last relation is not on screen:\n{screen}"
);
assert!(
screen.contains("No comments yet."),
"the body ends past the last screenful:\n{screen}"
);
}
/// The detail view is the second renderer of a ticket body, so it resolves a
/// relation the way `show` does rather than printing the uuid the file stores.
///
@@ -4058,8 +4279,9 @@ mod tests {
let mut board = one_board(&dir);
board.toggle_detail();
let text = &board.detail.as_ref().expect("no detail").text;
assert!(text.contains("blocked by (2222222) The target"), "{text:?}");
let text = &board.detail.as_ref().expect("no detail").plain();
// Marked with the target's status, backlog, and the mark sits ahead of the id.
assert!(text.contains("blocked by \u{2581} (2222222) The target"), "{text:?}");
assert!(!text.contains(target), "the bare uuid was drawn: {text:?}");
}
@@ -4082,8 +4304,8 @@ mod tests {
board.select_card(1, SCREEN);
board.toggle_detail();
let text = &board.detail.as_ref().expect("no detail").text;
assert!(text.contains("blocks (1111111) A holder"), "{text:?}");
let text = &board.detail.as_ref().expect("no detail").plain();
assert!(text.contains("blocks \u{2581} (1111111) A holder"), "{text:?}");
}
/// The detail view resolves the Campaign field the way `show` does. The field stores
@@ -4109,7 +4331,7 @@ mod tests {
let mut board = one_board(&dir);
board.toggle_detail();
let text = &board.detail.as_ref().expect("no detail").text;
let text = &board.detail.as_ref().expect("no detail").plain();
assert!(text.contains("(ccccccc) v1 release"), "{text:?}");
assert!(!text.contains(campaign), "the bare uuid reached the screen: {text:?}");
}
@@ -4130,7 +4352,7 @@ mod tests {
let mut board = one_board(&dir);
board.toggle_detail();
let text = &board.detail.as_ref().expect("no detail").text;
let text = &board.detail.as_ref().expect("no detail").plain();
assert!(text.contains("A description."), "the body was lost: {text:?}");
// No campaigns to resolve against, so the reference reads as gone.
assert!(text.contains("_missing_"), "{text:?}");
@@ -4152,7 +4374,7 @@ mod tests {
let mut board = one_board(&dir);
board.toggle_detail();
let text = &board.detail.as_ref().expect("no detail").text;
let text = &board.detail.as_ref().expect("no detail").plain();
assert!(text.contains("A description."), "the body was lost: {text:?}");
}
}
+354 -66
View File
@@ -539,8 +539,12 @@ pub fn format_comments_with(
/// an edit at every call site.
#[derive(Default)]
pub struct Resolved {
/// The block [`render_relations`] built, or empty for a ticket with no relations.
pub relations: String,
/// The relations of the ticket, both directions, from [`relations_for`]. Empty for a
/// ticket with none at either end.
///
/// Rows rather than the rendered block: the CLI paints them into escapes and the
/// board styles the same rows itself, since a paragraph is no place for an escape.
pub relations: Vec<RelationRow>,
/// The Campaign value as it reads, from [`reference_cell`]. Empty leaves the stored
/// value to render as it sits, which is what a ticket in no campaign wants.
pub campaign: String,
@@ -555,7 +559,7 @@ pub fn content_trim_colored(content: &str, resolved: &Resolved) -> String {
/// The rule is measured on the name as displayed, in characters. It used to span the
/// raw line, so it ran three past the heading for the `## `, and byte length over-drew
/// anything non-ASCII.
fn push_heading(out: &mut String, heading: &str, colored: bool) {
fn push_heading(out: &mut Body, heading: &str, colored: bool) {
let name = heading.strip_prefix("## ").unwrap_or(heading);
out.push_str(&paint(name, Color::Orange, colored));
@@ -572,10 +576,70 @@ fn push_heading(out: &mut String, heading: &str, colored: bool) {
///
/// [`Resolved`] carries the parts that come from elsewhere on the board, since the
/// body alone cannot render them.
/// One piece of the rendered body: text as it prints, or relations still as rows.
///
/// The body is one string to the CLI and a run of styled lines to the board, and the
/// only part that differs is the relations block. Splitting the body here rather than
/// building it twice is what keeps the two views from drifting: everything outside the
/// block is rendered once, by [`content_parts`], and the rows are handed on unpainted.
pub enum BodyPart {
Text(String),
Relations(Vec<RelationRow>),
}
/// The body under construction. Text accumulates into the trailing run, and a relations
/// block closes it, so a caller pushes text and rows without tracking which it pushed
/// last.
#[derive(Default)]
struct Body {
parts: Vec<BodyPart>,
}
impl Body {
fn push_str(&mut self, text: &str) {
match self.parts.last_mut() {
Some(BodyPart::Text(run)) => run.push_str(text),
_ => self.parts.push(BodyPart::Text(text.to_string())),
}
}
fn push(&mut self, c: char) {
match self.parts.last_mut() {
Some(BodyPart::Text(run)) => run.push(c),
_ => self.parts.push(BodyPart::Text(c.to_string())),
}
}
fn push_relations(&mut self, rows: &[RelationRow]) {
self.parts.push(BodyPart::Relations(rows.to_vec()));
}
/// Whether the text written so far ends with `suffix`. A relations block never does,
/// since it is not text yet.
fn ends_with(&self, suffix: &str) -> bool {
match self.parts.last() {
Some(BodyPart::Text(run)) => run.ends_with(suffix),
_ => false,
}
}
}
pub fn content_trim(content: &str, colored: bool, resolved: &Resolved) -> String {
let relations = resolved.relations.as_str();
content_parts(content, colored, resolved)
.iter()
.map(|part| match part {
BodyPart::Text(text) => text.clone(),
BodyPart::Relations(rows) => render_relations(rows, colored),
})
.collect()
}
/// The body rendered into its parts, with the colour decision already applied to the
/// text and deliberately not to the relations.
pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<BodyPart> {
let relations = resolved.relations.as_slice();
let lines: Vec<&str> = content.trim().lines().collect();
let mut result = String::new();
let mut result = Body::default();
let mut current_section = "";
let mut criterion = 0;
let mut i = 0;
@@ -598,7 +662,7 @@ pub fn content_trim(content: &str, colored: bool, resolved: &Resolved) -> String
// after everything.
if is_metadata_heading(line) && !stores_relations && !relations.is_empty() {
push_heading(&mut result, RELATIONS.heading, colored);
result.push_str(relations);
result.push_relations(relations);
result.push('\n');
shown_relations = true;
}
@@ -622,7 +686,7 @@ pub fn content_trim(content: &str, colored: bool, resolved: &Resolved) -> String
// holds the same edges resolved to a title, and the inverses with them.
if line.trim_end() == RELATIONS.heading && !relations.is_empty() {
let end = section_end(&lines, i);
result.push_str(relations);
result.push_relations(relations);
// The blank line the skipped body ended with, before the next heading.
if end < lines.len() {
result.push('\n');
@@ -705,10 +769,10 @@ pub fn content_trim(content: &str, colored: bool, resolved: &Resolved) -> String
result.push('\n');
}
push_heading(&mut result, RELATIONS.heading, colored);
result.push_str(relations);
result.push_relations(relations);
}
result
result.parts
}
/// Colour the `1.` at the head of a numbered line, leaving the rest alone.
@@ -1640,86 +1704,222 @@ impl RelationIndex {
/// relations block and the Campaign field, so a dangling reference is spelled one way
/// wherever it is shown.
pub fn reference_cell(uuid: &str, name: Option<&str>, colored: bool) -> String {
let id = paint(short_id(uuid), Color::Red, colored);
paint_cells(&reference_cells(uuid, name), colored)
}
/// The same cross reference in cells, for a renderer that is not writing escapes.
///
/// The one spelling of a reference, so the relations block and the Campaign field cannot
/// come to say a dangling one differently, and the board draws the id in the colour the
/// guideline gives it rather than dropping every colour to stay safe.
pub fn reference_cells(uuid: &str, name: Option<&str>) -> Vec<Cell> {
let mut cells = vec![
Cell::plain("("),
Cell::colored(short_id(uuid), Color::Red),
Cell::plain(") "),
];
match name {
Some(name) => format!("({}) {}", id, name),
None => format!("({}) {}", id, paint("_missing_", Color::Grey, colored)),
Some(name) => cells.push(Cell::plain(name)),
None => cells.push(Cell::colored("_missing_", Color::Grey)),
}
cells
}
/// Cells as the CLI prints them: each one painted, or carried through as it stands.
pub fn paint_cells(cells: &[Cell], colored: bool) -> String {
cells
.iter()
.map(|cell| match cell.color {
Some(color) => paint(&cell.text, color, colored),
None => cell.text.clone(),
})
.collect()
}
/// The glyph and colour for the status of a relation's target.
///
/// A rising bar rather than a circle: the cards spend `\u{25cf}`, `\u{25d0}`, `\u{25cb}` and `\u{b7}` on the
/// priority meter, and another circle here would be read as one of those. The ramp is
/// also the meaning, backlog through done, so the shape says which status it is and the
/// colour only says that it is one. Block Elements are the same bet every heading rule
/// and every border on the board already makes.
///
/// One colour for all four, because the palette has none to spare: red is a uuid, green
/// a title, cyan a timestamp, grey an unset value, and orange is what Status already
/// means. Grey and `?` for a target the board does not hold, beside the `_missing_` that
/// grey already spells.
const STATUS_MARKS: [(&str, char); 4] = [
("backlog", '\u{2581}'),
("committed", '\u{2584}'),
("reviewing", '\u{2586}'),
("done", '\u{2588}'),
];
/// The mark for a status, or the missing mark for a target the board no longer holds.
///
/// An unrecognised status reads as missing rather than as a stage of the flow: the value
/// comes from the directory the ticket was found in, so it is one of the four, and
/// guessing at a fifth would put a mark on a status nothing can act on.
/// `every_status_has_a_mark` pins the pairing against `status_dirs`.
pub fn status_mark(status: Option<&str>) -> (char, Color) {
let found = status.and_then(|status| {
STATUS_MARKS
.iter()
.find(|(name, _)| *name == status)
.map(|(_, mark)| *mark)
});
match found {
Some(mark) => (mark, Color::Orange),
None => ('?', Color::Grey),
}
}
/// A relation's target as it reads.
fn target_cell(target: Option<&RelatedTicket>, uuid: &str, colored: bool) -> String {
reference_cell(uuid, target.map(|ticket| ticket.title.as_str()), colored)
/// One row of the Relations block: which relation, and what it points at.
///
/// The target is `None` for a uuid the board no longer holds, which is the one case that
/// has neither a title nor a status to show.
#[derive(Clone, Debug)]
pub struct RelationRow {
pub label: &'static str,
pub uuid: String,
pub target: Option<RelationTarget>,
}
/// The Relations section as it is shown, or empty when there is nothing to show.
/// What a relation points at, once the board has been read for it.
#[derive(Clone, Debug)]
pub struct RelationTarget {
pub title: String,
pub status: String,
}
/// A run of text and the colour it is drawn in, or `None` for the default foreground.
///
/// Both directions, stored first: the relations the ticket holds, then the ones held
/// against it, named from this end. Rendered from the index rather than from the body
/// alone, because a bare uuid says nothing and half the relations are not in the file.
pub fn render_relations(
stored: &[Relation],
index: &RelationIndex,
uuid: &str,
colored: bool,
) -> String {
let mut rows: Vec<(&'static str, String)> = stored
/// The unit both renderers take: [`paint`] turns one into an escape sequence for the
/// CLI, and the board turns the same one into a ratatui `Span`. A block laid out once
/// and painted twice cannot draw two different blocks.
#[derive(Clone, Debug)]
pub struct Cell {
pub text: String,
pub color: Option<Color>,
}
impl Cell {
fn plain(text: impl Into<String>) -> Self {
Cell {
text: text.into(),
color: None,
}
}
fn colored(text: impl Into<String>, color: Color) -> Self {
Cell {
text: text.into(),
color: Some(color),
}
}
}
/// The relations of one ticket, both directions, in the order they are shown.
///
/// Stored first: the relations the ticket holds, then the ones held against it, named
/// from this end. Read from the index rather than from the body alone, because a bare
/// uuid says nothing and half the relations are not in the file.
///
/// The single builder. Everything that shows a relation goes through these rows, so the
/// CLI and the board cannot disagree about which edges there are, what they are called
/// or which direction comes first.
pub fn relation_rows(stored: &[Relation], index: &RelationIndex, uuid: &str) -> Vec<RelationRow> {
let target_of = |ticket: Option<&RelatedTicket>| {
ticket.map(|ticket| RelationTarget {
title: ticket.title.clone(),
status: ticket.status.clone(),
})
};
let mut rows: Vec<RelationRow> = stored
.iter()
.map(|relation| {
(
relation.kind.label(),
target_cell(index.get(&relation.target), &relation.target, colored),
)
.map(|relation| RelationRow {
label: relation.kind.label(),
uuid: relation.target.clone(),
target: target_of(index.get(&relation.target)),
})
.collect();
rows.extend(index.inbound(uuid).into_iter().map(|(kind, holder)| {
(
kind.inverse_label(),
target_cell(Some(holder), &holder.uuid, colored),
)
RelationRow {
label: kind.inverse_label(),
uuid: holder.uuid.clone(),
target: target_of(Some(holder)),
}
}));
if rows.is_empty() {
return String::new();
}
rows
}
// Measured on the labels, which carry no colour, and padded before the target cell
// is joined on, for the reason the metadata table is: an escape sequence counted
// towards a width tilts the column the moment colour is on.
/// The Relations block laid out: one row of cells per relation, or nothing to show.
///
/// The layout lives here rather than in each renderer, so the mark, the padding and the
/// gutter are decided once. The labels are measured with no colour on them and padded
/// before the target is joined, for the reason the metadata table is: an escape sequence
/// counted towards a width tilts the column the moment colour is on.
pub fn relation_cells(rows: &[RelationRow]) -> Vec<Vec<Cell>> {
let width = rows
.iter()
.map(|(label, _)| label.chars().count())
.map(|row| row.label.chars().count())
.max()
.unwrap_or(0);
rows.iter()
.map(|row| {
let (mark, colour) = status_mark(row.target.as_ref().map(|target| target.status.as_str()));
let padding = " ".repeat(width - row.label.chars().count());
// The mark goes ahead of the id, where it describes the target rather than
// the row: every row carries one, so nothing is pushed out of line the way
// the card's blocked mark would have been.
let mut cells = vec![
Cell::plain(format!("{}{}{}", row.label, padding, COLUMN_GUTTER)),
Cell::colored(mark.to_string(), colour),
Cell::plain(" "),
];
cells.extend(reference_cells(
&row.uuid,
row.target.as_ref().map(|target| target.title.as_str()),
));
cells
})
.collect()
}
/// The Relations section as the CLI prints it, or empty when there is nothing to show.
pub fn render_relations(rows: &[RelationRow], colored: bool) -> String {
let mut out = String::new();
for (label, cell) in &rows {
out.push_str(label);
out.push_str(&" ".repeat(width - label.chars().count()));
out.push_str(COLUMN_GUTTER);
out.push_str(cell);
for row in relation_cells(rows) {
out.push_str(&paint_cells(&row, colored));
out.push('\n');
}
out
}
/// The rendered Relations block for one ticket, reading the board for the rest of it.
/// The relations of the ticket in `content`, read against the board around it.
///
/// The colour decision is passed in rather than asked for, like everything else the
/// body renders: the board draws the same text with colour off.
pub fn relations_block(content: &str, worklane_dir: &Path, colored: bool) -> Result<String> {
/// Rows rather than a rendered block: the board styles them itself, since an escape
/// sequence in a ratatui paragraph is drawn as literal bytes.
pub fn relations_for(content: &str, worklane_dir: &Path) -> Result<Vec<RelationRow>> {
let title = heading_title(content);
let stored = parse_relations(content, &title)?;
let index = RelationIndex::load(worklane_dir)?;
Ok(render_relations(
Ok(relation_rows(
&stored,
&index,
&parse_ticket_field(content, "ID"),
colored,
))
}
@@ -3202,6 +3402,19 @@ mod tests {
}
// --------------------------------------------------------------- relations --
/// One row as the block shows it, for a test about where the block goes rather than
/// about how it was derived.
fn row(label: &'static str, uuid: &str, title: &str, status: &str) -> RelationRow {
RelationRow {
label,
uuid: uuid.to_string(),
target: Some(RelationTarget {
title: title.to_string(),
status: status.to_string(),
}),
}
}
const TARGET: &str = "b1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
const SELF: &str = "641e3d5c-1b0e-4d2f-9a7e-3c8b5f0a2d61";
@@ -3327,30 +3540,105 @@ mod tests {
]);
let stored = vec![relation(RelationKind::RegressionOf, TARGET)];
// Each target marked with the status of the ticket it names: backlog for the
// blocker, reviewing for the other one.
assert_eq!(
render_relations(&stored, &index, SELF, false),
"regression of (b1b2c3d) The blocker\n\
blocks (ccccccc) The other one\n\
relates to (ccccccc) The other one\n"
render_relations(&relation_rows(&stored, &index, SELF), false),
"regression of \u{2581} (b1b2c3d) The blocker\n\
blocks \u{2586} (ccccccc) The other one\n\
relates to \u{2586} (ccccccc) The other one\n"
);
}
/// Every status the board holds has a mark of its own, and no two share one. Pinned
/// against `status_dirs` rather than the four names written out here, so a status
/// added later fails this instead of silently reading as missing.
#[test]
fn every_status_has_a_mark() {
let mut seen = std::collections::HashSet::new();
for status in status_dirs() {
let (mark, colour) = status_mark(Some(status));
assert_ne!(mark, '?', "{status} has no mark of its own");
assert_eq!(colour, Color::Orange, "{status} is not drawn as a status");
assert!(seen.insert(mark), "{status} shares its mark with another status");
}
assert_eq!(seen.len(), 4, "{seen:?}");
}
/// A target the board does not hold has no status to show, and a value that is not
/// one of the four is the same answer: `?` in grey, beside the grey `_missing_`.
#[test]
fn a_status_the_board_does_not_use_reads_as_missing() {
assert_eq!(status_mark(None), ('?', Color::Grey));
assert_eq!(status_mark(Some("elsewhere")), ('?', Color::Grey));
assert_eq!(status_mark(Some("")), ('?', Color::Grey));
}
/// The cards spend the circles on priority, two cells away from nothing at all, so a
/// status drawn as one would be read as a level.
#[test]
fn no_status_mark_is_a_priority_glyph() {
let levels = [1, 2, 3, 4, 5].map(|level| priority_mark(Priority::Level(level)).0);
let priority: String = levels
.iter()
.copied()
.chain([priority_mark(Priority::Unset).0])
.collect();
for status in status_dirs() {
let (mark, _) = status_mark(Some(status));
assert!(
!priority.contains(mark),
"{status} is drawn with {mark:?}, which the priority meter uses"
);
}
}
/// The mark on each row is the status of the ticket that row names, not of the ticket
/// being shown, so four relations in four statuses read four ways.
#[test]
fn the_block_marks_each_target_with_its_own_status() {
let rows: Vec<RelationRow> = status_dirs()
.into_iter()
.map(|status| row("relates to", TARGET, status, status))
.collect();
let rendered = render_relations(&rows, false);
for status in status_dirs() {
let (mark, _) = status_mark(Some(status));
assert!(
rendered.contains(&format!("{mark} (b1b2c3d) {status}")),
"no {status} row marked {mark:?}:\n{rendered}"
);
}
}
/// The id is kept, since it is the only thing left to go looking for, and the title
/// is `_missing_` rather than a bare uuid pretending to be one.
#[test]
fn a_target_the_board_does_not_have_renders_as_missing() {
let stored = vec![relation(RelationKind::BlockedBy, TARGET)];
// `?` rather than a stage of the flow: there is no status to show, and the mark
// has to say that as plainly as `_missing_` says the title does not exist.
assert_eq!(
render_relations(&stored, &RelationIndex::new(Vec::new()), SELF, false),
"blocked by (b1b2c3d) _missing_\n"
render_relations(
&relation_rows(&stored, &RelationIndex::new(Vec::new()), SELF),
false
),
"blocked by ? (b1b2c3d) _missing_\n"
);
}
#[test]
fn a_ticket_with_no_relations_at_either_end_renders_no_block() {
let index = RelationIndex::new(vec![related(TARGET, "Elsewhere", "backlog", Vec::new())]);
assert_eq!(render_relations(&[], &index, SELF, false), "");
assert_eq!(
render_relations(&relation_rows(&[], &index, SELF), false),
""
);
}
/// Without the guard every ticket with no ID field relates to every other one that
@@ -3376,10 +3664,10 @@ mod tests {
"# T\n\n## Relations\n- blocked by {}\n\n## Metadata\n\n- **ID**: {}\n",
TARGET, SELF
);
let rendered = content_trim(&content, false, &Resolved { relations: "blocked by (b1b2c3d) The blocker\n".to_string(), ..Default::default() });
let rendered = content_trim(&content, false, &Resolved { relations: vec![row("blocked by", TARGET, "The blocker", "backlog")], ..Default::default() });
assert!(
rendered.contains("Relations\n─────────\n\nblocked by (b1b2c3d) The blocker\n\nMetadata"),
rendered.contains("Relations\n─────────\n\nblocked by \u{2581} (b1b2c3d) The blocker\n\nMetadata"),
"{rendered:?}"
);
assert!(!rendered.contains(TARGET), "the bare uuid was printed: {rendered:?}");
@@ -3391,10 +3679,10 @@ mod tests {
#[test]
fn the_body_injects_the_block_when_the_file_has_no_section() {
let content = format!("# T\n\n## Description\nBody.\n\n## Metadata\n\n- **ID**: {}\n", SELF);
let rendered = content_trim(&content, false, &Resolved { relations: "blocks (641e3d5) The gated one\n".to_string(), ..Default::default() });
let rendered = content_trim(&content, false, &Resolved { relations: vec![row("blocks", SELF, "The gated one", "committed")], ..Default::default() });
assert!(
rendered.contains("Body.\n\nRelations\n─────────\n\nblocks (641e3d5) The gated one\n\nMetadata"),
rendered.contains("Body.\n\nRelations\n─────────\n\nblocks \u{2584} (641e3d5) The gated one\n\nMetadata"),
"{rendered:?}"
);
}
@@ -3403,9 +3691,9 @@ mod tests {
/// worth more at the end than dropped.
#[test]
fn the_body_appends_the_block_when_there_is_no_metadata() {
let rendered = content_trim("# T\n\n## Description\nBody.\n", false, &Resolved { relations: "blocks (641e3d5) X\n".to_string(), ..Default::default() });
let rendered = content_trim("# T\n\n## Description\nBody.\n", false, &Resolved { relations: vec![row("blocks", SELF, "X", "done")], ..Default::default() });
assert!(rendered.ends_with("Relations\n─────────\n\nblocks (641e3d5) X\n"), "{rendered:?}");
assert!(rendered.ends_with("Relations\n─────────\n\nblocks \u{2588} (641e3d5) X\n"), "{rendered:?}");
}
/// No block and a section holding only its placeholder: the section renders as it