Mark a relation by its kind rather than its target's status, and bump to 0.15.1

A column of ▁▄▆█ read as undifferentiated blocks. What is worth seeing at a
glance is which kind of edge a row is: × for blocked by and blocks, → for
relates to, ← for regression of and regressed by. The labels are five long words
that blur when one ticket carries several, and the rows holding it up are now
the crosses.

Both directions of a kind carry one mark, since blocked by and blocks are the
same edge read from two ends and the label is what says which end you are on.

× is BLOCKED_MARK, the constant a held-up card already draws, in the same
brightred. On a card it says this ticket is held up, in the block that this edge
is what holds one, which is one word, so one glyph and one definition: the
constant moved to util.rs, where both renderers can reach it. Brightred rather
than the red asked for, because the id one cell to the right is red and the two
would have blended.

The arrows are the ones the footer already draws, so they render wherever it
does, and no_relation_mark_is_a_priority_glyph pins all three against every
level of the meter: the circles belong to priority.

The mark now survives a target the board cannot find, because a kind is read
from the ticket's own file rather than from the board. Only the name is gone,
and `_missing_` in grey is what says so. That is one case fewer than the status
mark had, which needed a `?` for a target with no status to show.

What this gives up is the status: 6ce2c47's motivation was reading whether a
blocker is finished without leaving the overlay, and nothing in the block shows
that now. Its criteria 1 and 3 describe the commit before this one, and the
ticket says so.

RelationTarget went with it. Nothing read the status field once the mark stopped
keying on it, and a field written but never shown is a field that goes stale
unnoticed, so RelationRow carries the kind and the title and the status is one
lookup away on the index if a later ticket wants it.

A patch, not a second minor: 0.15.0 was the arrival of a mark and settling which
glyph it is belongs to that, where a second minor would read as two features.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-22 15:35:24 +02:00
co-authored by Claude Opus 5
parent ce32b42ae4
commit 5ae9c7fe00
7 changed files with 165 additions and 159 deletions
+19 -17
View File
@@ -1209,15 +1209,6 @@ fn aligned_offset(offset: u16, start: u16, end: u16, inner: u16, total: u16) ->
offset.min(total.saturating_sub(inner))
}
/// The mark a card carries while it waits on a ticket that is not done.
///
/// Not a fourth circle. The Geometric Shapes glyphs belong to the priority meter, and
/// another one two cells away from it would read as part of that ramp rather than as a
/// different fact. A multiplication sign is Latin-1, like the middle dot the unset
/// priority draws, so it renders wherever the meter already does. That is the same
/// safe-glyph rule that took the quadrant circles out of the ramp.
const BLOCKED_MARK: &str = "\u{d7}";
/// One card as four corners with the title between them:
///
/// ```text
@@ -4130,7 +4121,7 @@ mod tests {
board: &Board,
width: u16,
height: u16,
symbol: char,
symbol: &str,
) -> Option<ratatui::style::Color> {
let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
terminal.draw(|frame| draw(frame, board)).unwrap();
@@ -4138,7 +4129,7 @@ mod tests {
(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())
.find(|(x, y)| buffer[(*x, *y)].symbol() == symbol)
.map(|(x, y)| buffer[(x, y)].fg)
}
@@ -4174,7 +4165,7 @@ mod tests {
let mut board = one_board(&dir);
board.toggle_detail();
let (mark, colour) = status_mark(Some("reviewing"));
let (mark, colour) = relation_mark(RelationKind::BlockedBy);
let detail = board.detail.as_ref().expect("no detail");
assert!(
detail.plain().contains(mark),
@@ -4346,8 +4337,13 @@ mod tests {
Some(Color::Red.into()),
"the id went with the title it could not find"
);
// `?` rather than a stage of the flow, in grey rather than the status orange.
assert_eq!(span_color(&row, "?"), Some(Color::Grey.into()));
// The mark is the kind, read off this ticket's own file, so it survives a target
// the board cannot find: only the name is gone.
assert_eq!(
span_color(&row, BLOCKED_MARK),
Some(Color::BrightRed.into()),
"the mark went with the title it could not find"
);
}
/// The detail view is the second renderer of a ticket body, so it resolves a
@@ -4372,8 +4368,11 @@ mod tests {
board.toggle_detail();
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:?}");
// Marked for its kind, and the mark sits ahead of the id.
assert!(
text.contains(&format!("blocked by {BLOCKED_MARK} (2222222) The target")),
"{text:?}"
);
assert!(!text.contains(target), "the bare uuid was drawn: {text:?}");
}
@@ -4397,7 +4396,10 @@ mod tests {
board.toggle_detail();
let text = &board.detail.as_ref().expect("no detail").plain();
assert!(text.contains("blocks \u{2581} (1111111) A holder"), "{text:?}");
assert!(
text.contains(&format!("blocks {BLOCKED_MARK} (1111111) A holder")),
"{text:?}"
);
}
/// The detail view resolves the Campaign field the way `show` does. The field stores
+113 -116
View File
@@ -1738,61 +1738,59 @@ pub fn paint_cells(cells: &[Cell], colored: bool) -> String {
.collect()
}
/// The glyph and colour for the status of a relation's target.
/// The mark a blocking relation carries, and a card waiting on one.
///
/// 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.
/// Not a fourth circle. The Geometric Shapes glyphs belong to the priority meter, and
/// another one two cells away from it would read as part of that ramp rather than as a
/// different fact. A multiplication sign is Latin-1, like the middle dot the unset
/// priority draws, so it renders wherever the meter already does. That is the same
/// safe-glyph rule that took the quadrant circles out of the ramp.
///
/// 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}'),
];
/// One glyph for both places, since both say the same word: on a card that this ticket
/// is held up, in the relations block that this edge is what holds one. The direction is
/// the label's to say.
pub const BLOCKED_MARK: &str = "\u{d7}";
/// 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)
});
/// The mark a `relates to` row carries: a plain pointer to somewhere else worth reading.
pub const RELATES_MARK: &str = "\u{2192}";
match found {
Some(mark) => (mark, Color::Orange),
None => ('?', Color::Grey),
/// The mark a regression row carries, pointing back at the fix it undid.
pub const REGRESSION_MARK: &str = "\u{2190}";
/// The glyph and colour for a kind of relation.
///
/// The label already names the kind in words, and this is what makes the block scannable
/// without reading them: the rows that hold you up are the red crosses, whichever
/// direction they point. Arrows and a cross rather than shapes from the priority
/// vocabulary, and all three are in the ramp the footer's own `\u{2190}\u{2192}\u{2191}\u{2193}` already draws.
///
/// The colours reuse the palette the way the priority meter does, as a small ramp inside
/// one column rather than as new meanings: brightred is the cross a card already draws,
/// cyan the pointer, orange the way back. Nothing here is a colour standing in for a
/// uuid or a title, which are what sit beside it on the row.
pub fn relation_mark(kind: RelationKind) -> (&'static str, Color) {
match kind {
RelationKind::BlockedBy => (BLOCKED_MARK, Color::BrightRed),
RelationKind::RelatesTo => (RELATES_MARK, Color::Cyan),
RelationKind::RegressionOf => (REGRESSION_MARK, Color::Orange),
}
}
/// 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.
/// The title is `None` for a uuid the board no longer holds, which is the one case with
/// nothing to name.
#[derive(Clone, Debug)]
pub struct RelationRow {
/// Which edge this is, which decides the mark. Kept beside the label rather than
/// derived from it: the label is the same word for both directions of `relates to`,
/// and reading a kind back out of prose is how a mark comes to disagree with a row.
pub kind: RelationKind,
/// The kind as it reads from this end, which is what the row is padded against.
pub label: &'static str,
pub uuid: String,
pub target: Option<RelationTarget>,
}
/// 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,
/// The title of the ticket it names, once the board has been read for it.
pub title: Option<String>,
}
/// A run of text and the colour it is drawn in, or `None` for the default foreground.
@@ -1832,27 +1830,24 @@ impl Cell {
/// 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| RelationRow {
kind: relation.kind,
label: relation.kind.label(),
uuid: relation.target.clone(),
target: target_of(index.get(&relation.target)),
title: index
.get(&relation.target)
.map(|ticket| ticket.title.clone()),
})
.collect();
rows.extend(index.inbound(uuid).into_iter().map(|(kind, holder)| {
RelationRow {
kind,
label: kind.inverse_label(),
uuid: holder.uuid.clone(),
target: target_of(Some(holder)),
title: Some(holder.title.clone()),
}
}));
@@ -1874,7 +1869,7 @@ pub fn relation_cells(rows: &[RelationRow]) -> Vec<Vec<Cell>> {
rows.iter()
.map(|row| {
let (mark, colour) = status_mark(row.target.as_ref().map(|target| target.status.as_str()));
let (mark, colour) = relation_mark(row.kind);
let padding = " ".repeat(width - row.label.chars().count());
// The mark goes ahead of the id, where it describes the target rather than
@@ -1882,13 +1877,10 @@ pub fn relation_cells(rows: &[RelationRow]) -> Vec<Vec<Cell>> {
// 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::colored(mark, colour),
Cell::plain(" "),
];
cells.extend(reference_cells(
&row.uuid,
row.target.as_ref().map(|target| target.title.as_str()),
));
cells.extend(reference_cells(&row.uuid, row.title.as_deref()));
cells
})
@@ -3404,14 +3396,12 @@ mod tests {
/// 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 {
fn row(kind: RelationKind, label: &'static str, uuid: &str, title: &str) -> RelationRow {
RelationRow {
kind,
label,
uuid: uuid.to_string(),
target: Some(RelationTarget {
title: title.to_string(),
status: status.to_string(),
}),
title: Some(title.to_string()),
}
}
@@ -3540,46 +3530,68 @@ 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.
// Each row marked for its own kind: the way back for the regression, the cross
// for the block, the pointer for the neighbour.
assert_eq!(
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"
format!(
"regression of {REGRESSION_MARK} (b1b2c3d) The blocker\n\
blocks {BLOCKED_MARK} (ccccccc) The other one\n\
relates to {RELATES_MARK} (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.
/// Every kind has a mark of its own, and no two share one: the mark is what makes the
/// block scannable without reading the labels, so two kinds drawn alike would defeat
/// it.
#[test]
fn every_status_has_a_mark() {
fn every_relation_kind_has_a_mark_of_its_own() {
let kinds = [
RelationKind::BlockedBy,
RelationKind::RelatesTo,
RelationKind::RegressionOf,
];
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");
for kind in kinds {
let (mark, colour) = relation_mark(kind);
assert!(!mark.is_empty(), "{kind:?} has no mark");
assert!(seen.insert(mark), "{kind:?} shares its mark with another kind");
assert_ne!(
colour,
Color::Green,
"{kind:?} is drawn in the colour that means a title"
);
}
assert_eq!(seen.len(), 4, "{seen:?}");
assert_eq!(seen.len(), 3, "{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_`.
/// Both directions of one kind carry the same mark, since the kind is what the mark
/// says and the label is what says which way it points.
#[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));
fn both_directions_of_a_kind_carry_one_mark() {
let index = RelationIndex::new(vec![
related(TARGET, "The blocker", "backlog", Vec::new()),
related(
"cccccccc-1111-4222-8333-444444444444",
"The held one",
"backlog",
vec![relation(RelationKind::BlockedBy, SELF)],
),
]);
let stored = vec![relation(RelationKind::BlockedBy, TARGET)];
let rendered = render_relations(&relation_rows(&stored, &index, SELF), false);
assert!(rendered.contains(&format!("blocked by {BLOCKED_MARK} (b1b2c3d)")), "{rendered}");
assert!(rendered.contains(&format!("blocks {BLOCKED_MARK} (ccccccc)")), "{rendered}");
}
/// 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.
/// relation drawn as one would be read as a level.
#[test]
fn no_status_mark_is_a_priority_glyph() {
fn no_relation_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()
@@ -3587,30 +3599,15 @@ mod tests {
.chain([priority_mark(Priority::Unset).0])
.collect();
for status in status_dirs() {
let (mark, _) = status_mark(Some(status));
for kind in [
RelationKind::BlockedBy,
RelationKind::RelatesTo,
RelationKind::RegressionOf,
] {
let (mark, _) = relation_mark(kind);
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}"
"{kind:?} is drawn with {mark:?}, which the priority meter uses"
);
}
}
@@ -3621,14 +3618,14 @@ mod tests {
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.
// The mark is the kind, which is known from the ticket's own file, so it survives
// a target the board cannot find. `_missing_` is what says the target is gone.
assert_eq!(
render_relations(
&relation_rows(&stored, &RelationIndex::new(Vec::new()), SELF),
false
),
"blocked by ? (b1b2c3d) _missing_\n"
format!("blocked by {BLOCKED_MARK} (b1b2c3d) _missing_\n")
);
}
@@ -3664,10 +3661,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: vec![row("blocked by", TARGET, "The blocker", "backlog")], ..Default::default() });
let rendered = content_trim(&content, false, &Resolved { relations: vec![row(RelationKind::BlockedBy, "blocked by", TARGET, "The blocker")], ..Default::default() });
assert!(
rendered.contains("Relations\n─────────\n\nblocked by \u{2581} (b1b2c3d) The blocker\n\nMetadata"),
rendered.contains(&format!("Relations\n─────────\n\nblocked by {BLOCKED_MARK} (b1b2c3d) The blocker\n\nMetadata")),
"{rendered:?}"
);
assert!(!rendered.contains(TARGET), "the bare uuid was printed: {rendered:?}");
@@ -3679,10 +3676,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: vec![row("blocks", SELF, "The gated one", "committed")], ..Default::default() });
let rendered = content_trim(&content, false, &Resolved { relations: vec![row(RelationKind::BlockedBy, "blocks", SELF, "The gated one")], ..Default::default() });
assert!(
rendered.contains("Body.\n\nRelations\n─────────\n\nblocks \u{2584} (641e3d5) The gated one\n\nMetadata"),
rendered.contains(&format!("Body.\n\nRelations\n─────────\n\nblocks {BLOCKED_MARK} (641e3d5) The gated one\n\nMetadata")),
"{rendered:?}"
);
}
@@ -3691,9 +3688,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: vec![row("blocks", SELF, "X", "done")], ..Default::default() });
let rendered = content_trim("# T\n\n## Description\nBody.\n", false, &Resolved { relations: vec![row(RelationKind::BlockedBy, "blocks", SELF, "X")], ..Default::default() });
assert!(rendered.ends_with("Relations\n─────────\n\nblocks \u{2588} (641e3d5) X\n"), "{rendered:?}");
assert!(rendered.ends_with(&format!("Relations\n─────────\n\nblocks {BLOCKED_MARK} (641e3d5) X\n")), "{rendered:?}");
}
/// No block and a section holding only its placeholder: the section renders as it