From 7a0dd625cedc032418611054cd175003753b444b Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Sat, 22 Aug 2026 03:13:56 +0200 Subject: [PATCH] (1e7b1a9) Colour a tag by its name, and bump to 0.13.2 FNV-1a over the tag bytes into an eight-colour reserved palette, so the same tag is the same colour on every card and on every board with nothing stored. The hash is written out rather than taken from std, whose output is not promised stable across releases. The index is multiply-shift, not `% len`. The length is a power of two, so a modulus keeps the low three bits of the hash, and FNV-1a's low bits carry only the low bits of the input bytes: nothing moves information downwards. Every pair of tags differing above bit 2 landed in one slot, `bug` and `BUG` among them. It looked like a good palette, two colliding cards in sixty-four on this board, because the vocabulary had been folded into a handful of slots. Using the whole hash gives 14/64, which is the real arithmetic for eight colours. The palette is reserved as a list and disjoint from the seven colours that already mean something: a tag in red reads as a uuid, in green as a title. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 5 + Cargo.lock | 2 +- Cargo.toml | 2 +- src/tui.rs | 42 +++++++-- src/util.rs | 263 +++++++++++++++++++++++++++++++++++++++++++++++++++- 5 files changed, 302 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0da8b17..cc07511 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -201,6 +201,11 @@ 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 +- **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 +- **The index is multiply-shift, not `% TAG_COLORS.len()`.** The length is a power of two, so a modulus keeps only the low three bits of the hash, and FNV-1a's low bits carry only the low bits of the input bytes: multiplication cannot move information downwards. Under a modulus every pair of tags differing above bit 2, `bug` and `BUG` among them, landed in one slot regardless of the rest of the string. It looked like a *good* palette on this board, two colliding cards out of sixty-four, because the vocabulary had been folded into a handful of slots. Taking the top bits of a 128-bit product uses the whole hash +- Eight tag colours means roughly one card in five shows two tags alike. That is arithmetic and is accepted: the colour groups a tag across cards, it does not tell two tags apart within one, and the tag text is beside it either way. Do not widen the list to chase the number on one board - Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. `\x1b[38;5;8m` is byte for byte what crossterm emits for ratatui's `Color::DarkGray`, the grey frig and pantop use for dimmed rows ### Code Organization diff --git a/Cargo.lock b/Cargo.lock index ae4ee10..57cd5ba 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.13.1" +version = "0.13.2" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 65b42d1..2672e8f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.13.1" +version = "0.13.2" edition = "2024" [dependencies] diff --git a/src/tui.rs b/src/tui.rs index f3d6056..e1f05e7 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -921,6 +921,10 @@ fn card_lines(card: &Card, selected: bool, width: u16) -> Vec> { /// corner: a cut list reads as a shorter one, and `bug` and `bugfix` truncated to the /// same width say the same thing. An untagged ticket spends no row at all, the way a /// short title spends no second one. +/// +/// Each tag carries its own colour, from `tag_color`, so the same tag is the same +/// colour on every card in every column. The row is spans rather than one string for +/// that reason alone; it is still measured as one string. fn tags_line(tags: &[String], width: u16) -> Option> { if tags.is_empty() { return None; @@ -932,14 +936,25 @@ fn tags_line(tags: &[String], width: u16) -> Option> { .collect::>() .join(" "); + // Measured on the raw row, before anything is styled. What fits must not depend on + // the colour decision, or a card would hold its tags in one render and drop them in + // the other. if row.chars().count() > width as usize { return None; } - Some(Line::from(Span::styled( - row, - Style::default().fg(Color::Grey.into()), - ))) + let mut spans = Vec::with_capacity(tags.len() * 2); + for (index, tag) in tags.iter().enumerate() { + if index > 0 { + spans.push(Span::raw(" ")); + } + spans.push(Span::styled( + format!("#{tag}"), + Style::default().fg(tag_color(tag).into()), + )); + } + + Some(Line::from(spans)) } /// The project name as it fits beside the mark and the id. @@ -1645,14 +1660,23 @@ mod tests { assert!(rows[3].starts_with("alice"), "the owner moved: {rows:?}"); } - /// Dimmed like the owner and the count beside it: the row is there to be scanned, - /// not to compete with the title. + /// Each tag carries its own colour, so the row can be scanned for one tag rather + /// than read word by word. The row used to be a single grey span, which is what + /// made a card of three tags one undifferentiated run. #[test] - fn the_tag_row_is_dimmed() { + fn each_tag_on_a_card_carries_its_own_colour() { let dir = board_dir(); - write_tagged_card(&dir, "Short", "2026-12-31", "- [ ] One", "cli, tui"); + write_tagged_card(&dir, "Short", "2026-12-31", "- [ ] One", "cli, docs"); - assert_eq!(card_colour(&dir, 120, "#cli #tui"), Some(Color::Grey.into())); + let cli = card_colour(&dir, 120, "#cli"); + let docs = card_colour(&dir, 120, "#docs"); + + // Through `tag_color`, not against a literal: the card has to use the mapping, + // and the mapping is pinned by its own test in util.rs. + assert_eq!(cli, Some(tag_color("cli").into())); + assert_eq!(docs, Some(tag_color("docs").into())); + assert_ne!(cli, docs, "two tags rendered in one colour"); + assert_ne!(cli, Some(Color::Grey.into()), "the row is still flat grey"); } /// And an untagged one spends no row on them, the way a short title spends no diff --git a/src/util.rs b/src/util.rs index 984146d..cceb6d3 100644 --- a/src/util.rs +++ b/src/util.rs @@ -68,6 +68,17 @@ pub enum Color { Grey, Magenta, BrightRed, + // The eight the tag palette draws from. Named as colours rather than as `TagBlue`, + // because the enum is the palette and `TAG_COLORS` is what reserves them: a use + // belongs to the list that claims it, not to the name of the colour it claims. + Blue, + Sky, + Violet, + Pink, + Turquoise, + Olive, + Tan, + Steel, } impl Color { @@ -88,11 +99,23 @@ impl Color { Color::Magenta => "\x1b[1;35m", // Indexed, for the same reason grey is: this is the spelling that renders. Color::BrightRed => "\x1b[38;5;9m", + // The tag palette, indexed throughout. The basic slots are themed by the + // terminal and drift towards each other on a real palette, which is fine + // for seven colours that each mean something and useless for six that have + // to stay apart from those seven and from one another. + Color::Blue => "\x1b[38;5;33m", + Color::Sky => "\x1b[38;5;117m", + Color::Violet => "\x1b[38;5;99m", + Color::Pink => "\x1b[38;5;205m", + Color::Turquoise => "\x1b[38;5;43m", + Color::Olive => "\x1b[38;5;106m", + Color::Tan => "\x1b[38;5;137m", + Color::Steel => "\x1b[38;5;67m", } } /// Every colour in the palette, so a test can walk them without listing them. - pub const ALL: [Color; 7] = [ + pub const ALL: [Color; 15] = [ Color::Red, Color::Cyan, Color::Orange, @@ -100,9 +123,95 @@ impl Color { Color::Grey, Color::Magenta, Color::BrightRed, + Color::Blue, + Color::Sky, + Color::Violet, + Color::Pink, + Color::Turquoise, + Color::Olive, + Color::Tan, + Color::Steel, ]; } +/// The colours a tag may be drawn in. +/// +/// Deliberately disjoint from the seven that already carry a meaning, per the guideline +/// in AGENTS.md: a tag in red reads as a uuid, in green as a title, in grey as an unset +/// value. Reserving slots here rather than picking at the call site is what keeps the +/// next colour someone assigns from landing on top of the tags. +/// +/// Eight, and a real board carries more tags than that, so two tags will share a +/// colour. That is accepted rather than designed around: the colour groups one tag +/// across cards, it does not identify it, and the tag is written out beside it either +/// way. Nothing pure can do better, since a function of the tag alone cannot know what +/// else sits on the card. +/// +/// Eight rather than six because two tags on one card collide at roughly `1 / n`, so +/// the only lever is the size of the list. It stops here because these are the slots +/// the assigned meanings leave: red, orange, green, cyan, magenta and grey are spoken +/// for, and a ninth would have to be a shade of one of the eight. Two colours nobody +/// can tell apart are a collision by another name. +/// +/// At eight, about a fifth of the cards on this board show two tags in one colour. That +/// is the arithmetic, not a fault to fix: the colour groups one tag *across* cards, so +/// a repeat within a card costs nothing that the tag text beside it does not answer. +/// +/// Do not tune this against the tags on one board. The count of collisions on any given +/// board swings either side of the average on the luck of the hash, and picking the +/// length that flatters today's vocabulary would be fitting to noise. An earlier draft +/// scored two collisions in sixty-four here, which looked like a good palette and was +/// really a broken index folding the whole vocabulary into a handful of slots. +pub const TAG_COLORS: [Color; 8] = [ + Color::Blue, + Color::Sky, + Color::Violet, + Color::Pink, + Color::Turquoise, + Color::Olive, + Color::Tan, + Color::Steel, +]; + +/// FNV-1a, 64 bit, over the bytes of the tag. +/// +/// Written out rather than taken from `std`: `DefaultHasher` is explicitly not promised +/// to keep its output stable across releases, and a board that repaints itself on a +/// toolchain upgrade has lost the one property this is for. Nine lines and no +/// dependency buys a mapping that is the same on every machine and every version. +fn fnv1a(bytes: &[u8]) -> u64 { + const OFFSET: u64 = 0xcbf2_9ce4_8422_2325; + const PRIME: u64 = 0x0000_0100_0000_01b3; + + let mut hash = OFFSET; + for byte in bytes { + hash ^= u64::from(*byte); + hash = hash.wrapping_mul(PRIME); + } + hash +} + +/// The colour a tag is drawn in, derived from the tag itself. +/// +/// A pure function of the string, so the same tag is the same colour on every card, in +/// every view and on every board, with nothing stored and nothing to keep in step. Two +/// boards that have never met agree about `bug`. +/// +/// Case sensitive, because `Bug` and `bug` are two different tags everywhere else in +/// worklane. Colouring them alike would be the display claiming a sameness the filter +/// and the field do not have. +pub fn tag_color(tag: &str) -> Color { + // Multiply-shift, not `% len`. The palette length is a power of two, so a modulus + // would keep the low three bits of the hash, and FNV-1a's low bits carry only the + // low bits of the input bytes: the multiply cannot move information downwards and + // the xor never does. `bug` and `BUG` differ in bit 5 of every letter, so under a + // modulus they landed in the same slot no matter what else the strings held, as did + // every other pair differing only above bit 2. Taking the top bits of the product + // uses the whole hash, which is where the avalanche is. + let index = (u128::from(fnv1a(tag.as_bytes())) * TAG_COLORS.len() as u128) >> 64; + TAG_COLORS[index as usize] +} + /// The same palette as ratatui sees it. /// /// Chosen to match what crossterm emits for the escape above, so a card in the TUI and @@ -119,6 +228,16 @@ impl From for ratatui::style::Color { Color::Grey => Tui::DarkGray, Color::Magenta => Tui::Magenta, Color::BrightRed => Tui::LightRed, + // Indexed on both sides, so the card and the listing are the same colour + // by construction rather than by two guesses that happen to agree. + Color::Blue => Tui::Indexed(33), + Color::Sky => Tui::Indexed(117), + Color::Violet => Tui::Indexed(99), + Color::Pink => Tui::Indexed(205), + Color::Turquoise => Tui::Indexed(43), + Color::Olive => Tui::Indexed(106), + Color::Tan => Tui::Indexed(137), + Color::Steel => Tui::Indexed(67), } } } @@ -673,9 +792,40 @@ fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) - return paint(value, Color::Grey, colored); } + if name == "Tags" { + return paint_tags(value, colored); + } + value.to_string() } +/// The stored tag list with each tag in its own colour. +/// +/// Painted in place rather than split and rejoined, so whatever separators the file +/// holds come back unchanged. `bug, cli` and `bug,cli` are both written by hand at some +/// point, and a cell that normalised them would be the display quietly disagreeing with +/// the file it is showing. +fn paint_tags(value: &str, colored: bool) -> String { + value + .split(',') + .map(|piece| { + let tag = piece.trim(); + if tag.is_empty() { + return piece.to_string(); + } + + let lead = piece.len() - piece.trim_start().len(); + format!( + "{}{}{}", + &piece[..lead], + paint(tag, tag_color(tag), colored), + &piece[lead + tag.len()..] + ) + }) + .collect::>() + .join(",") +} + /// Render the Metadata section as two aligned columns. /// /// Taken as a block rather than a line at a time because the field column cannot be @@ -2801,6 +2951,117 @@ mod tests { assert_eq!(seen.len(), Color::ALL.len()); } + /// The text a cell holds once its colour is taken off, so a test can assert the + /// separators survived without spelling out the escapes around them. + fn strip_escapes(text: &str) -> String { + let mut out = String::with_capacity(text.len()); + let mut rest = text; + while let Some(at) = rest.find('\x1b') { + out.push_str(&rest[..at]); + match rest[at..].find('m') { + Some(end) => rest = &rest[at + end + 1..], + None => return out, + } + } + out.push_str(rest); + out + } + + #[test] + fn a_tag_keeps_its_colour_and_different_tags_do_not_all_share_one() { + assert_eq!(tag_color("bug"), tag_color("bug")); + assert_eq!(tag_color("frontend"), tag_color("frontend")); + + let spread: std::collections::HashSet = + ["bug", "feature", "cli", "tui", "docs", "chore", "output", "skills"] + .iter() + .map(|tag| tag_color(tag)) + .collect(); + assert!(spread.len() > 3, "the mapping collapses the vocabulary: {spread:?}"); + } + + /// Case sensitive on purpose: `Bug` and `bug` are two different tags to the field + /// and to every search, so one colour for both would be the display claiming a + /// sameness nothing else has. + /// + /// Over a set rather than one pair. Any single pair can land in the same slot by + /// luck, one time in `TAG_COLORS.len()`, and a test that reads that accident as + /// case folding would be asserting the hash rather than the rule. + #[test] + fn tag_colour_does_not_fold_case() { + let folded = ["bug", "cli", "tui", "docs", "chore"] + .iter() + .all(|tag| tag_color(tag) == tag_color(&tag.to_uppercase())); + assert!(!folded, "tag_color lowercases before hashing"); + } + + /// Pinned so that a change to the hash is a failing test rather than a board that + /// quietly repaints itself. If this fails, the mapping moved: decide whether that + /// was intended before rewriting the expectations. + #[test] + fn the_tag_mapping_is_pinned() { + assert_eq!(tag_color("bug"), Color::Blue); + assert_eq!(tag_color("feature"), Color::Blue); + assert_eq!(tag_color("cli"), Color::Steel); + assert_eq!(tag_color("tui"), Color::Violet); + assert_eq!(tag_color("docs"), Color::Tan); + assert_eq!(tag_color("chore"), Color::Sky); + assert_eq!(tag_color("skills"), Color::Tan); + assert_eq!(tag_color("output"), Color::Blue); + } + + /// The whole reason the tag palette is a reserved list rather than a pick at the + /// call site: a tag drawn in red reads as a uuid, in green as a title, in grey as + /// an unset value. + #[test] + fn no_tag_colour_carries_another_meaning() { + for assigned in [ + Color::Red, + Color::Orange, + Color::Cyan, + Color::Green, + Color::Grey, + Color::Magenta, + Color::BrightRed, + ] { + assert!( + !TAG_COLORS.contains(&assigned), + "{assigned:?} means something else already" + ); + } + + // The priority ramp is the other list that claims colours, and it is built from + // the assigned seven rather than named here, so ask it directly. + for level in PRIORITY_RANGE { + let ramp = priority_mark(Priority::Level(level)).1; + assert!(!TAG_COLORS.contains(&ramp), "{ramp:?} is a priority colour"); + } + } + + #[test] + fn the_tags_cell_paints_each_tag_and_leaves_the_separators_alone() { + let plain = metadata_value_cell("Tags", "bug, cli", false, ""); + assert_eq!(plain, "bug, cli", "colour off must be the stored value"); + + let painted = metadata_value_cell("Tags", "bug, cli", true, ""); + assert!(painted.contains(&paint("bug", tag_color("bug"), true))); + assert!(painted.contains(&paint("cli", tag_color("cli"), true))); + + // The separator the file holds comes back as it went in, spacing and all. + assert_eq!(strip_escapes(&painted), "bug, cli"); + assert_eq!(strip_escapes(&metadata_value_cell("Tags", "bug,cli", true, "")), "bug,cli"); + assert_eq!(strip_escapes(&metadata_value_cell("Tags", " bug , cli ", true, "")), " bug , cli "); + } + + /// An unset value stays grey, since the Tags branch sits behind the unknown check. + #[test] + fn an_unset_tags_cell_is_still_grey() { + assert_eq!( + metadata_value_cell("Tags", "_None_", true, ""), + paint("_None_", Color::Grey, true) + ); + } + /// Pinned deliberately. Both SGR spellings of grey failed on a real palette, /// 90 reading nearly as light as the foreground and 37 sitting on top of it. /// This is the exact sequence crossterm emits for ratatui's Color::DarkGray,