diff --git a/AGENTS.md b/AGENTS.md index 55705bb..b409651 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ ### Color and Output - Use `color_text()` helper for colored output — it respects `should_use_colors()` (terminal detection) -- Color codes are defined in `get_color()`: red (31), cyan (36), orange (33), green (32), grey (38;5;8), magenta (1;35) +- Color codes are defined in `get_color()`: red (31), cyan (36), orange (33), green (32), grey (38;5;8), magenta (1;35), brightred (38;5;9) - Reset color with `\x1b[0m` after colored text - Bold uses `\x1b[1;35m` (magenta bold) - Always test color output works correctly in both terminal and pipe modes @@ -44,6 +44,7 @@ - Timestamp → cyan (36) - 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 - 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 74dc051..2787026 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1029,7 +1029,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.1.2" +version = "0.2.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 809038e..32c867e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.1.2" +version = "0.2.0" edition = "2024" [dependencies] diff --git a/src/command.rs b/src/command.rs index da78245..3528a2e 100644 --- a/src/command.rs +++ b/src/command.rs @@ -1,6 +1,12 @@ use clap::Parser; -use crate::util::PRIORITY_RANGE; +use std::sync::LazyLock; + +use crate::util::{PRIORITY_RANGE, priority_legend}; + +/// clap wants a `&str` with a long enough lifetime, and the legend is built from +/// the same ramp the listing uses rather than spelled out a second time. +static PRIORITY_LEGEND: LazyLock = LazyLock::new(priority_legend); /// Reject a level outside the range at parse time, so no command has to. fn priority_level(raw: &str) -> Result { @@ -72,6 +78,7 @@ pub enum Command { }, /// List tickets, optionally filtered by status + #[command(after_help = PRIORITY_LEGEND.as_str())] Ls { /// Filter by status (backlog, committed, reviewing, done) status: Option, diff --git a/src/util.rs b/src/util.rs index 72def90..513aea6 100644 --- a/src/util.rs +++ b/src/util.rs @@ -67,6 +67,8 @@ pub fn get_color(color: &str) -> &'static str { // Bold, per the guideline in AGENTS.md. Its absence meant colorize_line // asked for a colour that did not exist and got an empty prefix. "magenta" => "\x1b[1;35m", + // Indexed, for the same reason grey is: this is the spelling that renders. + "brightred" => "\x1b[38;5;9m", _ => "", } } @@ -349,6 +351,21 @@ pub fn colorize_metadata(line: &str) -> String { return line.to_string(); } + // Priority reads as a glyph here too, while the file keeps storing the number. + if let Some(value) = line.split("**Priority**:").nth(1) { + let priority = match value.trim().parse::() { + Ok(level) if PRIORITY_RANGE.contains(&level) => Priority::Level(level), + _ if is_unknown_value(value.trim()) => Priority::Unset, + _ => Priority::Invalid, + }; + return format!( + "- {}: {} {}", + color_text("Priority", "red"), + show_priority(priority), + value.trim() + ); + } + let content = line; let open_pos = match content.find("**") { Some(p) => p, @@ -557,15 +574,54 @@ fn dim_if_unset(value: &str) -> String { } } -/// How a level reads in a listing. -fn show_priority(priority: Priority) -> String { +/// The mark and colour for a level, from one place. +/// +/// A two-segment meter that empties as the level rises, so the level is legible +/// from shape alone: colour is off whenever output is piped, and NO_COLOR turns it +/// off in a terminal too, so colour accentuates and never encodes. +/// +/// Only three glyphs, the ones frig uses for its status indicators and which are +/// therefore known to render here. The quadrant circles this first used are in a +/// quarter as many fonts, so terminals substituted them from a fallback font that +/// draws them oversized. Two cells of a three-level ramp gives five steps of ink, +/// 2, 1.5, 1, 0.5, 0, without leaving that safe set. +/// +/// The number counts up while the mark empties out, because 1 is the most urgent. +/// That is the convention every tracker uses and what the p1 tags this replaced +/// already meant. +pub fn priority_mark(priority: Priority) -> (&'static str, &'static str) { match priority { - Priority::Level(level) => level.to_string(), - Priority::Unset => color_text("-", "grey"), - Priority::Invalid => color_text("?", "red"), + Priority::Level(1) => ("\u{25cf}\u{25cf}", "brightred"), + Priority::Level(2) => ("\u{25cf}\u{25d0}", "red"), + Priority::Level(3) => ("\u{25cf}\u{25cb}", "orange"), + Priority::Level(4) => ("\u{25d0}\u{25cb}", "cyan"), + Priority::Level(5) => ("\u{25cb}\u{25cb}", "grey"), + // Unreachable while Level is only built by parse_priority, which checks + // the range, but a level added later should not silently render blank. + Priority::Level(_) | Priority::Invalid => ("??", "brightred"), + Priority::Unset => ("\u{b7}\u{b7}", "grey"), } } +/// The legend, for help text. Nothing else in a listing explains the glyphs. +pub fn priority_legend() -> String { + let levels = PRIORITY_RANGE + .map(|level| { + let (glyph, _) = priority_mark(Priority::Level(level)); + format!("{} {}", glyph, level) + }) + .collect::>() + .join(" "); + + let (unset, _) = priority_mark(Priority::Unset); + format!("Priority: {levels} {unset} unset 1 is most urgent") +} + +fn show_priority(priority: Priority) -> String { + let (glyph, colour) = priority_mark(priority); + color_text(glyph, colour) +} + pub fn display_ticket_items(items: &[TicketItem]) { for item in items { let id = color_text(&item.id, "red"); @@ -720,9 +776,115 @@ mod tests { ); } + #[test] + fn each_level_gets_its_own_glyph_and_colour() { + let marks: Vec<_> = PRIORITY_RANGE + .map(|level| priority_mark(Priority::Level(level))) + .collect(); + + let glyphs: std::collections::HashSet<_> = marks.iter().map(|(g, _)| *g).collect(); + assert_eq!(glyphs.len(), marks.len(), "two levels share a glyph"); + + let colours: std::collections::HashSet<_> = marks.iter().map(|(_, c)| *c).collect(); + assert_eq!(colours.len(), marks.len(), "two levels share a colour"); + } + + /// The glyph has to carry the level with colour off, which is how every pipe + /// and every opencode tool reads it. + #[test] + fn the_glyph_alone_distinguishes_every_state() { + let mut seen = std::collections::HashSet::new(); + for state in PRIORITY_RANGE.map(Priority::Level).chain([Priority::Unset, Priority::Invalid]) { + let (glyph, _) = priority_mark(state); + assert!(seen.insert(glyph), "{glyph} is used for more than one state"); + } + } + + #[test] + fn the_fullest_mark_is_the_most_urgent() { + assert_eq!(priority_mark(Priority::Level(1)).0, "\u{25cf}\u{25cf}"); + assert_eq!(priority_mark(Priority::Level(5)).0, "\u{25cb}\u{25cb}"); + } + + /// Every mark is the same width, or the column stops lining up. + #[test] + fn every_mark_is_the_same_width() { + let widths: std::collections::HashSet = PRIORITY_RANGE + .map(Priority::Level) + .chain([Priority::Unset, Priority::Invalid]) + .map(|p| priority_mark(p).0.chars().count()) + .collect(); + assert_eq!(widths, std::collections::HashSet::from([2])); + } + + /// The marks are built only from what frig already renders in this terminal: + /// the quadrant circles are in a quarter as many fonts and got substituted + /// from a fallback font that drew them oversized. + #[test] + fn marks_use_only_the_glyphs_known_to_render() { + let allowed = ['\u{25cf}', '\u{25d0}', '\u{25cb}', '\u{b7}', '?']; + for state in PRIORITY_RANGE + .map(Priority::Level) + .chain([Priority::Unset, Priority::Invalid]) + { + for ch in priority_mark(state).0.chars() { + assert!(allowed.contains(&ch), "{ch:?} is outside the safe set"); + } + } + } + + #[test] + fn the_meter_empties_as_the_level_rises() { + let ink = |p: Priority| -> f32 { + priority_mark(p) + .0 + .chars() + .map(|c| match c { + '\u{25cf}' => 1.0, + '\u{25d0}' => 0.5, + _ => 0.0, + }) + .sum() + }; + let mut previous = f32::MAX; + for level in PRIORITY_RANGE { + let current = ink(Priority::Level(level)); + assert!(current < previous, "level {level} does not empty further"); + previous = current; + } + } + + #[test] + fn an_invalid_level_is_marked_wrong_not_unset() { + assert_eq!(priority_mark(Priority::Invalid).0, "??"); + assert_ne!( + priority_mark(Priority::Invalid), + priority_mark(Priority::Unset) + ); + } + + #[test] + fn the_legend_covers_every_level_and_says_which_way_it_runs() { + let legend = priority_legend(); + for level in PRIORITY_RANGE { + let (glyph, _) = priority_mark(Priority::Level(level)); + assert!(legend.contains(glyph), "{glyph} missing from the legend"); + assert!(legend.contains(&level.to_string())); + } + assert!(legend.contains("most urgent"), "direction not spelled out"); + } + + /// Green means title; a priority must not borrow it. + #[test] + fn the_ramp_avoids_green() { + for level in PRIORITY_RANGE { + assert_ne!(priority_mark(Priority::Level(level)).1, "green"); + } + } + #[test] fn every_colour_the_code_asks_for_exists() { - for colour in ["red", "cyan", "orange", "green", "grey", "magenta"] { + for colour in ["red", "cyan", "orange", "green", "grey", "magenta", "brightred"] { assert!(!get_color(colour).is_empty(), "{colour} is not defined"); } } diff --git a/tests/cmd_ls.rs b/tests/cmd_ls.rs index b6447ee..a47def2 100644 --- a/tests/cmd_ls.rs +++ b/tests/cmd_ls.rs @@ -274,3 +274,25 @@ fn ls_filters_by_priority_and_composes_with_status() { assert!(stdout.contains("Lower one")); assert!(!stdout.contains("Urgent one")); } + +#[test] +fn ls_shows_a_mark_for_the_level() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket_with_priority(&worklane, "Top level", "1"); + create_ticket_with_priority(&worklane, "Bottom level", "5"); + create_ticket(&worklane, "backlog", "Nothing set", "alice", "_Not set_"); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()).arg("ls").arg("backlog"); + let stdout = get_stdout(&mut cmd); + + // Piped, so no escapes: the glyph is carrying the level by itself + assert!(!stdout.contains('\u{1b}')); + assert!(stdout.contains("\u{25cf}\u{25cf} "), "no full meter for level 1 in {stdout:?}"); + assert!(stdout.contains("\u{25cb}\u{25cb} "), "no empty meter for level 5"); + assert!(stdout.contains("\u{b7}\u{b7} "), "no unset mark"); + // The raw number is not what the listing shows + assert!(!stdout.contains(" 1 "), "the digit leaked into the row"); +} diff --git a/tests/cmd_show.rs b/tests/cmd_show.rs index 231efbc..def21fa 100644 --- a/tests/cmd_show.rs +++ b/tests/cmd_show.rs @@ -393,3 +393,30 @@ fn show_searches_across_all_statuses() { assert!(stdout.contains("Committed Task")); assert!(stdout.contains("This is in committed.")); } + +#[test] +fn show_renders_the_priority_mark_beside_the_number() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let filename = "abc123def456789012345678901234567890_prio.md"; + fs::write( + worklane.join("backlog").join(filename), + "# Prio Ticket\n\n## Metadata\n\n- **ID**: abc123def456789012345678901234567890\n\ + - **Priority**: 2\n- **Status**: backlog\n", + ) + .unwrap(); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(&temp.path()).arg("show").arg("Prio"); + let stdout = get_stdout(&mut cmd); + + // Mark for the eye, number still there for the file's sake + assert!(stdout.contains("\u{25cf}\u{25d0}"), "no mark in {stdout:?}"); + assert!(stdout.contains("Priority")); + assert!(stdout.contains('2')); + + // And the file itself is untouched + let content = fs::read_to_string(worklane.join("backlog").join(filename)).unwrap(); + assert!(content.contains("- **Priority**: 2")); +}