Compare commits

..
2 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 ae3ee1bb9e Show the target's status beside the relation kind, and bump to 0.15.2
A row now carries two marks, kind then status: what sort of edge this is, then
how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`.
Two questions are asked of this block, which rows hold this ticket up and
whether the ones that do are finished, and one glyph could not answer both.

○ not started, ◐ under way, ● finished, in grey, orange, cyan and green: the
shape says how far the target has got and the colour tells the two middle
stages apart, since committed and reviewing are both half circles. Green is the
colour the priority ramp deliberately leaves out because it means a title; on a
one-cell mark with no title behind it nothing else wants it, and it is the
obvious colour for done. Orange keeps the meaning it already has, Status.

These are the priority meter's own circles, and what keeps a status from
reading as a level is width: the meter is always two cells, a status mark is
one. the_status_mark_is_one_cell_where_the_meter_is_two pins both halves, and a
card carries the meter and never a status mark while the block carries the
status mark and never a meter.

The kind mark survives a target the board cannot find and the status mark
cannot, since a kind is read from the ticket's own file and a status from the
board. ? holds the column so the id does not move when one target has gone, and
_missing_ is what says it is gone.

Committed and reviewing are told apart by colour alone, so a pipe cannot tell
them apart: both read as under way. Accepted, since ● and ○ are the two answers
usually wanted and show on the target settles the rest, and assets/SKILL.md now
says so outright rather than leaving an agent to work it out from a colourless
half circle.

RelationTarget is back, carrying the title and the status in one Option because
they come from the same lookup. It went out in 5ae9c7f when nothing read the
status and came back one commit later, which is what a field nothing reads
costs: right at the time, churn either way.

A patch: 0.15.0 was the arrival of a marked relations block and this is still
settling what it marks. Three minors in an hour would read as three features.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 15:59:22 +02:00
Ansho ReiandClaude Opus 5 5ae9c7fe00 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>
2026-08-22 15:35:24 +02:00
7 changed files with 331 additions and 127 deletions
+15 -6
View File
@@ -159,7 +159,7 @@ and this file is for what someone changing worklane's own code needs.
- The criteria count is a field on `TicketItem`, filled in `collect_ticket_items` where the file is already being read, and counted through `criteria()` so a checkbox in a description is not counted here or numbered by `show`. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. `None` rather than `[0/0]` for a ticket with no criteria
- **The tags go under the title, dimmed, each prefixed with `#`.** The field was invisible on the board: nothing said a ticket was tagged `bug` without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
- `tags` is a field on `TicketItem`, filled in `collect_ticket_items` through `parse_tags`, for the reason the criteria count is. `parse_tags` splits the comma-separated field into whole trimmed values, so a caller asking for `bug` is not answered by `bugfix`, and reads absent, `_None_` and empty as the same answer
- **A held-up card carries `×` after its id, in brightred.** A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
- **A held-up card carries `BLOCKED_MARK`, `×`, after its id, in brightred.** The constant lives in `util.rs` and the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
- **The mark goes after the id, not before it.** Ahead of the id it would push every id in the column out of line whenever one card was blocked, which costs more than one card's state is worth. It is measured before the project label and the due date, so both give way to it: those are context for a ticket somebody can start, and this is the one thing on a card that says not to. Dropped whole when the row cannot hold the identity and the mark together, the rule a corner follows
- **`blocked` is on `Card`, not on `TicketItem`.** The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way `project` is. What `collect_ticket_items` fills is the ticket's own `uuid` and its `blockers`, both read off the file it is already holding; `mark_blocked` then walks the four columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw
- **A blocker the board does not hold marks nothing**, the answer `mv` already gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exception `detail_of` makes for the same reason: `show` and `mv` are where a hand-edited file is reported, and a board that will not draw because one ticket is malformed is the worse failure
@@ -205,10 +205,17 @@ and this file is for what someone changing worklane's own code needs.
- **One builder, two painters.** `relation_rows` decides which edges there are, what they are called and which direction comes first; `relation_cells` decides the layout, the mark and the colours; `paint_cells` turns cells into escapes for the CLI and `span_of` turns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent
- **`Cell` is the unit both renderers take**: a run of text and the colour it is drawn in, `None` for the default foreground. The same trick as the palette itself, where `Color::ansi()` and `From<Color> for ratatui::style::Color` keep one colour from existing for one renderer and not the other
- **`reference_cells` is the one spelling of a cross reference**, and `reference_cell` is it painted. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown
- **The status mark is a rising bar, `▁▄▆█`, and `?` for a target the board does not hold.** Not a circle: the cards spend `●◐○·` on the priority meter and another circle would be read as a level. The ramp is also the meaning, backlog through done, so the shape says which status it is. Block Elements are the same bet every heading rule and every border on the board already makes
- **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, which is why that one sits after the id and this one before it
- **An unrecognised status reads as missing, not as a stage of the flow.** The value comes from the directory the ticket was found in, so it is one of the four; 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`, so a status added later fails a test instead of silently reading as `?`
- **`show` and the board carry the same mark**, decided here rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minor
- **A row carries two marks, kind then status**: what sort of edge this is, then how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished
- The status went through one bad shape first. It was a rising bar, `▁▄▆█`, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer
- **Both directions of a kind carry one mark.** `blocked by` and `blocks` are the same edge read from two ends, and the label is what says which end you are on. `both_directions_of_a_kind_carry_one_mark` pins it
- **`×` is `BLOCKED_MARK`, the same constant a held-up card draws**, in the same brightred. On a card it says this ticket is held up and in the block it says this edge is what holds one, which is one word, so one glyph and one definition. It lives in `util.rs` for that reason, not in `tui.rs` where the card is
- **The kind marks stay out of the priority vocabulary**, which owns `●◐○·`, and `no_relation_mark_is_a_priority_glyph` pins that against every level. They are the arrows the footer already draws, so they render wherever it does
- **The status marks are those very circles, and what keeps them from reading as a level is width**: the meter is always two cells and a status mark is one. `the_status_mark_is_one_cell_where_the_meter_is_two` pins both halves. A card carries the meter and never a status mark, and the block carries the status mark and never a meter, so the two never sit in one column
- **Both marks go ahead of the id**, where they describe the target rather than the row. Every row carries both, so nothing is pushed out of line the way the card's blocked mark would have been, which is why that one sits after the id and these before it
- **The kind mark survives a target the board cannot find and the status mark cannot**, since a kind is read from the ticket's own file and a status from the board. `?` holds the column so the id does not move, and `_missing_` in grey is what says the target is gone
- **Committed and reviewing are told apart by colour alone**, both being `◐`, so a pipe cannot tell them apart: `should_use_colors` is false and both read as under way. Accepted, because `●` and `○` are the two answers usually wanted and `show` on the target settles the rest, and `assets/SKILL.md` says so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else
- `RelationTarget` carries the title and the status in one `Option`, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either way
- **`show` and the board carry the same mark**, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minor
- **`Resolved.relations` is rows, not a rendered block.** That is what lets the board style them: an escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so the block cannot arrive pre-painted. `content_parts` hands the text through already painted and the rows through untouched, which is the asymmetry the two renderers need
- **`BodyPart` splits the body rather than building it twice.** Everything outside the relations block is rendered once, by `content_parts`; `content_trim` is that with the rows painted, and the board is that with the rows styled. `Body` is the accumulator, so a caller pushes text and rows without tracking which it pushed last
- **`Detail.body` is a `Text`, and it is the only thing measured.** `last_offset` and the `Paragraph` both take it, so the clamp cannot wrap the body differently from the draw. `Detail::plain()` flattens it for the suite and is `#[cfg(test)]`: a second representation carried alongside the spans is a second thing to disagree
@@ -266,7 +273,8 @@ and this file is for what someone changing worklane's own code needs.
- Title → green (32)
- Unknown values (`_None_`, `_Not set_`) → grey (38;5;8)
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Relation status mark → orange for all four statuses, grey for a target the board does not hold. **The shape carries which status it is and the colour only says that it is one**, because there is no colour left to spend: red is a uuid, green a title, cyan a timestamp, grey an unset value, and orange is what Status already means. Four new meanings would have had to come out of `TAG_COLORS`, which is reserved. Grey on the missing mark is the meaning grey already has, beside the `_missing_` it sits next to
- Relation kind mark → brightred `×` blocked by and blocks, cyan `→` relates to, orange `←` regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `?` for a target the board does not hold. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
- **The palette splits in two: seven colours that each mean one thing, and `TAG_COLORS`, the eight a tag may be drawn in.** A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour in `TAG_COLORS`, and do not draw a tag in one outside it
- `tag_color()` is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, because `Bug` and `bug` are two different tags to the field and to every search
- **The hash is FNV-1a written out here, not `DefaultHasher`.** std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for. `the_tag_mapping_is_pinned` fails on any change to it, so a repaint is a decision rather than a surprise
@@ -302,6 +310,7 @@ and this file is for what someone changing worklane's own code needs.
- Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
- **Changed output means the CLI's output.** That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
- **Settling output that shipped one version ago is a patch**, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features
- No bump for docs-only, tests-only or `--fixup` commits
- When one body of work spans several commits, bump once on the final commit rather than on each
- Bump `Cargo.toml` and the `worklane` entry in `Cargo.lock` together, in the commit that carries the bump
Generated
+1 -1
View File
@@ -1494,7 +1494,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.15.0"
version = "0.15.2"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.15.0"
version = "0.15.2"
edition = "2024"
[dependencies]
+12 -4
View File
@@ -141,10 +141,18 @@ Recording a relation the ticket already holds reports no change. A ticket cannot
to itself, and a target that later disappears shows as `_missing_` rather than silently
going away.
`show` marks each target with the status of the ticket it names, a rising bar from
backlog to done: `▁` backlog, `▄` committed, `▆` reviewing, `█` done, and `?` for a target the
board no longer holds. So whether a blocker is finished is readable off the row without a
second `show`. The board draws the same block.
`show` marks each row twice, kind then status. The kind is `×` for `blocked by` and
`blocks`, `→` for `relates to`, `←` for `regression of` and `regressed by`; both
directions of one kind carry one mark, and the label is what says which end you are on.
The status is the target's own: `○` backlog, `◐` committed or reviewing, `●` done, and
`?` for a target the board no longer holds. So `blocked by × ● (1b78a24)` is a blocker
that is finished and `blocked by × ○ (1b78a24)` is one nobody has started. The board
draws the same block.
Colour is what tells committed from reviewing, since both are `◐`, and **your output is a
pipe, so you do not get the colour**. Read `◐` as under way, and if it matters which
stage, `worklane show` on that target says so in its Status field. `●` and `○` are
unambiguous without it, which are the two answers usually being asked for.
## Campaigns
+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", status_mark(Some("backlog")).0)),
"{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", status_mark(Some("backlog")).0)),
"{text:?}"
);
}
/// The detail view resolves the Campaign field the way `show` does. The field stores
+257 -84
View File
@@ -1738,57 +1738,106 @@ 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 a `relates to` row carries: a plain pointer to somewhere else worth reading.
pub const RELATES_MARK: &str = "\u{2192}";
/// The mark a regression row carries, pointing back at the fix it undid.
pub const REGRESSION_MARK: &str = "\u{2190}";
/// The mark for the status of a relation's target, and the colour it is drawn in.
///
/// One circle where the priority meter is always two, which is what keeps the two apart:
/// the meter reads `\u{25cf}\u{25d0}` and a status reads `\u{25d0}`, and they never sit in the same column.
/// `the_status_mark_is_one_cell_where_the_meter_is_two` pins that, since it is the whole
/// reason a circle is safe here when it is not safe on a card.
///
/// `\u{25cb}` not started, `\u{25d0}` under way, `\u{25cf}` finished, so the shape carries how far the
/// target has got and the colour says which of the two middle stages it is in. A ramp
/// inside one column, the way the priority meter reuses the palette: grey for the pile
/// nobody has picked up, orange for work in hand, cyan for work waiting on a reader,
/// green for done. Green is the one the priority ramp deliberately leaves out because it
/// means a title, and it is safe on a one-cell mark that no title sits behind.
const STATUS_MARKS: [(&str, &str, Color); 4] = [
("backlog", "\u{25cb}", Color::Grey),
("committed", "\u{25d0}", Color::Orange),
("reviewing", "\u{25d0}", Color::Cyan),
("done", "\u{25cf}", Color::Green),
];
/// The mark for a status, or the missing mark for a target the board no longer holds.
/// The mark for a status, or `?` 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) {
/// A placeholder rather than a blank, so the id column does not move when one row's
/// target has gone, and grey rather than a stage of the flow: the `_missing_` beside it
/// is grey for the same reason. An unrecognised value reads the same way, since the
/// status comes from the directory the ticket was found in and guessing at a fifth stage
/// would mark a status nothing can act on. `every_status_has_a_mark` pins the pairing
/// against `status_dirs`.
pub fn status_mark(status: Option<&str>) -> (&'static str, Color) {
let found = status.and_then(|status| {
STATUS_MARKS
.iter()
.find(|(name, _)| *name == status)
.map(|(_, mark)| *mark)
.find(|(name, _, _)| *name == status)
.map(|(_, mark, colour)| (*mark, *colour))
});
match found {
Some(mark) => (mark, Color::Orange),
None => ('?', Color::Grey),
found.unwrap_or(("?", Color::Grey))
}
/// 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 target is `None` for a uuid the board no longer holds, which is the one case with
/// neither a name nor a status to show.
#[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,
/// The ticket it names, once the board has been read for it.
pub target: Option<RelationTarget>,
}
/// What a relation points at, once the board has been read for it.
/// What a relation points at: what to call it, and how far it has got.
///
/// One `Option` around both rather than two, because they come from the same lookup and
/// so are absent together. The status is here again after 5ae9c7f took it out: the mark
/// keyed on the kind alone for one commit, and a blocking row's state is the thing a
/// reader most wants without leaving the ticket.
#[derive(Clone, Debug)]
pub struct RelationTarget {
pub title: String,
@@ -1842,6 +1891,7 @@ pub fn relation_rows(stored: &[Relation], index: &RelationIndex, uuid: &str) ->
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)),
@@ -1850,6 +1900,7 @@ pub fn relation_rows(stored: &[Relation], index: &RelationIndex, uuid: &str) ->
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)),
@@ -1874,15 +1925,21 @@ 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 (kind, kind_colour) = relation_mark(row.kind);
let (status, status_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.
// Kind, then state, then who: what sort of edge this is, how far the ticket
// at the other end has got, and which ticket that is. Both marks go ahead of
// the id, where they describe the target rather than the row, and every row
// carries both, 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::colored(kind, kind_colour),
Cell::plain(" "),
Cell::colored(status, status_colour),
Cell::plain(" "),
];
cells.extend(reference_cells(
@@ -3404,8 +3461,15 @@ 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,
status: &str,
) -> RelationRow {
RelationRow {
kind,
label,
uuid: uuid.to_string(),
target: Some(RelationTarget {
@@ -3415,6 +3479,12 @@ mod tests {
}
}
/// The status mark as the block draws it, so a row assertion reads like the row.
/// The glyphs themselves are pinned literally by `the_status_marks_are_pinned`.
fn smark(status: &str) -> &'static str {
status_mark(Some(status)).0
}
const TARGET: &str = "b1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
const SELF: &str = "641e3d5c-1b0e-4d2f-9a7e-3c8b5f0a2d61";
@@ -3540,46 +3610,163 @@ 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} {backlog} (b1b2c3d) The blocker\n\
blocks {BLOCKED_MARK} {reviewing} (ccccccc) The other one\n\
relates to {RELATES_MARK} {reviewing} (ccccccc) The other one\n",
backlog = smark("backlog"),
reviewing = smark("reviewing"),
)
);
}
/// 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.
/// The mapping itself, literally, so a change to a glyph or a colour is a decision
/// rather than a surprise. Every other assertion about a row interpolates these.
#[test]
fn the_status_marks_are_pinned() {
assert_eq!(status_mark(Some("backlog")), ("\u{25cb}", Color::Grey));
assert_eq!(status_mark(Some("committed")), ("\u{25d0}", Color::Orange));
assert_eq!(status_mark(Some("reviewing")), ("\u{25d0}", Color::Cyan));
assert_eq!(status_mark(Some("done")), ("\u{25cf}", Color::Green));
assert_eq!(status_mark(None), ("?", Color::Grey));
}
/// Every status the board holds is told apart from the other three. The shape does
/// not do it alone, since committed and reviewing are both half circles, so it is the
/// pair that has to be unique. Pinned against `status_dirs` rather than the four
/// names written out here, so a status added later fails this instead of silently
/// reading as `?`.
#[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_ne!(mark, "?", "{status} has no mark of its own");
assert!(
seen.insert((mark, colour)),
"{status} is drawn exactly like 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_`.
/// An unrecognised value reads as missing rather than as a fifth stage of the flow.
#[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));
assert_eq!(status_mark(Some("elsewhere")), ("?", Color::Grey));
assert_eq!(status_mark(Some("")), ("?", Color::Grey));
}
/// The circles are the priority meter's glyphs, and this is what keeps a status from
/// being read as a level: the meter is always two cells and a status mark is one.
/// A card carries the meter and never a status mark; the block carries the status
/// mark and never a meter.
#[test]
fn the_status_mark_is_one_cell_where_the_meter_is_two() {
for status in status_dirs() {
assert_eq!(
status_mark(Some(status)).0.chars().count(),
1,
"{status} is drawn wide enough to read as a priority meter"
);
}
for priority in [
Priority::Level(1),
Priority::Level(3),
Priority::Level(5),
Priority::Unset,
] {
assert_eq!(
priority_mark(priority).0.chars().count(),
2,
"{priority:?} is drawn narrow enough to read as a status mark"
);
}
}
/// The mark on each row is the status of the ticket that row names, not of the ticket
/// being read, 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(RelationKind::RelatesTo, "relates to", TARGET, status, status))
.collect();
let rendered = render_relations(&rows, false);
for status in status_dirs() {
assert!(
rendered.contains(&format!("{} (b1b2c3d) {status}", smark(status))),
"no {status} row marked {:?}:\n{rendered}",
smark(status)
);
}
}
/// 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_relation_kind_has_a_mark_of_its_own() {
let kinds = [
RelationKind::BlockedBy,
RelationKind::RelatesTo,
RelationKind::RegressionOf,
];
let mut seen = std::collections::HashSet::new();
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(), 3, "{seen:?}");
}
/// 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 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);
let backlog = smark("backlog");
assert!(
rendered.contains(&format!("blocked by {BLOCKED_MARK} {backlog} (b1b2c3d)")),
"{rendered}"
);
assert!(
rendered.contains(&format!("blocks {BLOCKED_MARK} {backlog} (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 +3774,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 +3793,15 @@ 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 kind mark survives, since it is read from this ticket's own file, and the
// status mark cannot: `?` holds the column so the id does not move, and
// `_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 +3837,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", "backlog")], ..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", smark("backlog"))),
"{rendered:?}"
);
assert!(!rendered.contains(TARGET), "the bare uuid was printed: {rendered:?}");
@@ -3679,10 +3852,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", "committed")], ..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", smark("committed"))),
"{rendered:?}"
);
}
@@ -3691,9 +3864,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", "done")], ..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", smark("done"))), "{rendered:?}");
}
/// No block and a section holding only its placeholder: the section renders as it
+26 -14
View File
@@ -289,12 +289,20 @@ fn relate_leaves_everything_it_was_not_asked_about_alone() {
assert!(content.contains("- **Owner**: alice"), "{content}");
}
/// The mark each status prints before the id, a rising bar from backlog to done. Written
/// out rather than imported: these tests drive the binary, so they see only its output.
const BACKLOG_MARK: &str = "\u{2581}";
const DONE_MARK: &str = "\u{2588}";
/// What a target the board no longer holds prints instead, since it has no status.
const MISSING_MARK: &str = "?";
/// The mark each kind prints before the id. Written out rather than imported: these
/// tests drive the binary, so they see only its output.
///
/// The cross is the one a held-up card already carries, since both say the same word.
const BLOCKED_MARK: &str = "\u{d7}";
const RELATES_MARK: &str = "\u{2192}";
/// And the mark for the status of the ticket the row names, which follows the kind: a
/// circle filling up as the target moves through the flow.
const BACKLOG_MARK: &str = "\u{25cb}";
const DONE_MARK: &str = "\u{25cf}";
/// A target the board no longer holds has no status, and `?` holds the column so the id
/// does not move.
const NO_STATUS_MARK: &str = "?";
/// The kind, the short id and the title, so the section reads without a second lookup.
#[test]
@@ -307,7 +315,7 @@ fn show_renders_the_kind_the_short_id_and_the_title() {
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(shown.contains("Relations"), "{shown}");
assert!(
shown.contains(&format!("blocked by {BACKLOG_MARK} (b1b2c3d) The blocker")),
shown.contains(&format!("blocked by {BLOCKED_MARK} {BACKLOG_MARK} (b1b2c3d) The blocker")),
"{shown}"
);
// Never the stored line: a bare uuid says nothing about what it points at.
@@ -325,24 +333,28 @@ fn show_lists_the_relation_the_other_ticket_holds() {
let shown = stdout(&run(&temp, &["show", BLOCKER]));
assert!(
shown.contains(&format!("blocks {BACKLOG_MARK} (641e3d5) The gated one")),
shown.contains(&format!("blocks {BLOCKED_MARK} {BACKLOG_MARK} (641e3d5) The gated one")),
"{shown}"
);
assert!(!ticket(&worklane, BLOCKER).contains("Relations"));
// The mark is the target's status, not the shown ticket's: this row points at the
// one ticket in done, from a ticket in backlog, which is the question the mark is
// there to answer.
// Two kinds on one ticket, each with its own mark, and the second mark is the state
// of the ticket at the far end: the old fix is in done and the blocker is not. That
// is the pair the block is for, which kind of edge and whether it is finished.
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(
shown.contains(&format!("relates to {DONE_MARK} (f1f2f3f) The old fix")),
shown.contains(&format!("blocked by {BLOCKED_MARK} {BACKLOG_MARK} (b1b2c3d) The blocker")),
"{shown}"
);
assert!(
shown.contains(&format!("relates to {RELATES_MARK} {DONE_MARK} (f1f2f3f) The old fix")),
"{shown}"
);
// `relates to` is symmetric, so it reads the same way from either end.
let shown = stdout(&run(&temp, &["show", FIXED]));
assert!(
shown.contains(&format!("relates to {BACKLOG_MARK} (641e3d5) The gated one")),
shown.contains(&format!("relates to {RELATES_MARK} {BACKLOG_MARK} (641e3d5) The gated one")),
"{shown}"
);
}
@@ -357,7 +369,7 @@ fn a_target_that_no_longer_exists_renders_as_missing() {
let shown = stdout(&run(&temp, &["show", GATED]));
assert!(
shown.contains(&format!("blocked by {MISSING_MARK} (b1b2c3d) _missing_")),
shown.contains(&format!("blocked by {BLOCKED_MARK} {NO_STATUS_MARK} (b1b2c3d) _missing_")),
"{shown}"
);
}