diff --git a/Cargo.lock b/Cargo.lock index 143a5dd..bd6814b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.31.1" +version = "0.31.2" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 4ccdd95..524b67a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.31.1" +version = "0.31.2" edition = "2024" [dependencies] diff --git a/assets/SKILL.md b/assets/SKILL.md index e1a58c9..a3f868d 100644 --- a/assets/SKILL.md +++ b/assets/SKILL.md @@ -127,6 +127,11 @@ is never left half-marked. A criterion already in the state you asked for is rep unchanged rather than refused, and a call that would change nothing writes nothing. Both apply to `uncheck` exactly as they do to `check`. +**Say why on the unusual moves:** `worklane mv 1b78a24 --status backlog -f --reason "the +first plan was wrong"`. The reason is recorded inside the history entry beside the +transition it explains and rendered indented under its row, in `show` and on the board. +Optional on every move; a refused or no-op move records nothing even with one. + ## Filing a ticket ``` diff --git a/src/command.rs b/src/command.rs index 73c1df6..47aeeb1 100644 --- a/src/command.rs +++ b/src/command.rs @@ -230,6 +230,11 @@ pub enum Command { #[arg(long, help = ACTOR_HELP)] actor: Option, + + /// Why the ticket moved, recorded in the history entry beside the transition + /// it explains. Prose, so it takes a leading hyphen + #[arg(long, allow_hyphen_values = PROSE)] + reason: Option, }, /// Replace fields on an existing ticket diff --git a/src/handlers.rs b/src/handlers.rs index 0856844..af6c441 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -607,10 +607,20 @@ pub fn cmd_mv( target: Status, force: bool, actor: &Option, + reason: &Option, start: &Path, ) -> Result<()> { let target_status = target.as_str(); + // A reason is one fact on one line, which is how the renderer draws it, so a + // newline smuggled in through the shell collapses with the whitespace around it. + // All blank means none, rather than an empty field in the log. + let reason = reason + .as_deref() + .map(str::split_whitespace) + .map(|words| words.collect::>().join(" ")) + .unwrap_or_default(); + let worklane_dir = find_worklane_dir(start)?; let (current_status, title, resolved) = resolve_ticket(ticket_id, &worklane_dir)?; @@ -697,13 +707,14 @@ pub fn cmd_mv( // After the move, never before: an entry for a move that was refused would be a log // of things that did not happen. The no-op above returns without one for the same - // reason. + // reason, and without its --reason with it. write_entry( &worklane_dir, &parse_ticket_field(&resolved, "ID"), Kind::Status, &change(¤t_status, target_status), &resolve_actor(actor.as_deref()), + &reason, )?; println!( @@ -740,6 +751,7 @@ pub fn cmd_comment( Kind::Comment, body, &resolve_actor(actor.as_deref()), + "", )?; println!("Comment added to '{}' ({})", title, filename); @@ -988,6 +1000,7 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> { &parse_ticket_field(&content, "Tags"), ), &resolve_actor(args.actor.as_deref()), + "", )?; } @@ -1046,6 +1059,7 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> { &parse_ticket_field(&content, "Owner"), ), &resolve_actor(args.actor.as_deref()), + "", )?; let verb = match user { @@ -1615,6 +1629,7 @@ pub fn cmd_assign( Kind::Campaign, &change(&before, campaign.name()), &resolve_actor(actor.as_deref()), + "", )?; println!( diff --git a/src/history.rs b/src/history.rs index fa2d364..a7b71b4 100644 --- a/src/history.rs +++ b/src/history.rs @@ -123,6 +123,10 @@ pub struct Entry { pub time: String, /// A comment's text, or the before and after of the field a mechanical entry names. pub body: String, + /// Why a mechanical entry happened, as `mv --reason` gave it. Empty for every entry + /// that carries no such field, which is all of them but a reasoned move — including + /// every entry written before reasons existed. + pub reason: String, } /// Rename an old `comments` directory to `history`, before anything reads or writes it. @@ -187,12 +191,23 @@ fn parse_entry(filename: &str, content: &str) -> Entry { }) .unwrap_or(""); + // A missing reason is legitimate rather than unreadable, which is why this does not + // share the `unknown` fallback the two fields above carry: every entry written + // before `mv --reason` existed has none. + let reason = content + .lines() + .find_map(|line| line.strip_prefix("**Reason**:")) + .map(str::trim) + .unwrap_or_default() + .to_string(); + Entry { filename: filename.to_string(), kind, author: field("Author"), time: field("Time"), body: body.to_string(), + reason, } } @@ -267,19 +282,27 @@ pub fn count_comments(board: &Path, uuid: &str) -> usize { /// /// A comment's file is byte for byte what `comment` wrote before the kinds existed, so /// nothing has to be rewritten and a board can be read by either version. -fn entry_content(kind: Kind, body: &str, author: &str, time: &str) -> String { - format!( +/// +/// The optional reason rides after **Time**, so the two fields every entry has always +/// carried keep their places and an older binary reading this file finds its body and +/// fields exactly where they were. Empty writes no line, which is what keeps a reasoned +/// entry and one without reading as the same shape minus the field. +fn entry_content(kind: Kind, body: &str, author: &str, time: &str, reason: &str) -> String { + let mut content = format!( "{}\n\ - {}\n\ - \n\ - **Author**: {}\n\ - **Time**: {}\n\ - ", + {}\n\ + \n\ + **Author**: {}\n\ + **Time**: {}\n", kind.marker(), body, author, time - ) + ); + if !reason.is_empty() { + content.push_str(&format!("**Reason**: {}\n", reason)); + } + content } /// Write an entry under the first free name derived from the stamp. @@ -318,12 +341,16 @@ fn write_new(dir: &Path, stem: &str, content: &str) -> Result { /// move that was refused would be a log of things that did not happen. The cost of that /// order is that a failed write here leaves the edit in place and reports the failure, /// which is the right way round — the ticket is the record and this is the story of it. +/// +/// `reason` is the why [`Kind::Status`] can carry, from `mv --reason`; every other kind +/// passes the empty slice and gets no field written. pub fn write_entry( board: &Path, uuid: &str, kind: Kind, body: &str, author: &str, + reason: &str, ) -> Result { adopt_comments(board)?; @@ -332,7 +359,8 @@ pub fn write_entry( let now = Local::now(); let stem = format!("{}_{}", now.format(ENTRY_FILE_FORMAT), kind.slug()); - let content = entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string()); + let content = + entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string(), reason); write_new(&dir, &stem, &content) } @@ -382,7 +410,9 @@ pub fn history_cells(entries: &[Entry]) -> Vec { cells.push(Cell::plain("\n")); } // One line: a field change is one fact and a paragraph for it would bury the - // comments it sits between. + // comments it sits between. A reason grows an indented line under the row, + // the way a comment's text sits under its From header, so it reads as + // attached to the transition it explains rather than as the next entry. _ => { let padding = Kind::LABEL_WIDTH.saturating_sub(entry.kind.slug().chars().count()); cells.push(Cell::colored(entry.kind.slug(), Color::Orange)); @@ -391,6 +421,10 @@ pub fn history_cells(entries: &[Entry]) -> Vec { cells.push(Cell::plain(" ")); cells.push(Cell::colored(stamp, Color::Cyan)); cells.push(Cell::plain("\n")); + if !entry.reason.is_empty() { + cells.push(Cell::plain(format!(" {}", entry.reason))); + cells.push(Cell::plain("\n")); + } } } } @@ -411,7 +445,8 @@ mod tests { fn an_entry_names_its_kind_in_the_file_and_in_the_filename() { let board = board(); let filename = - write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude").unwrap(); + write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude", "") + .unwrap(); assert!(filename.ends_with("_status.md"), "was {filename}"); @@ -420,6 +455,37 @@ mod tests { assert_eq!(entries[0].kind, Kind::Status); assert_eq!(entries[0].body, "committed → reviewing"); assert_eq!(entries[0].author, "claude"); + assert_eq!(entries[0].reason, ""); + } + + /// One file, one event, its explanation: the reason rides in the entry that records + /// the transition it explains, as a field after **Time**, and round-trips. + #[test] + fn a_reason_is_recorded_in_the_file_and_read_back() { + let board = board(); + let filename = write_entry( + &board, + "uuid", + Kind::Status, + "reviewing → backlog", + "claude", + "sent back: the first plan was wrong", + ) + .unwrap(); + + let content = fs::read_to_string(history_dir(&board, "uuid").join(filename)).unwrap(); + assert!( + content.ends_with("**Reason**: sent back: the first plan was wrong\n"), + "{content}" + ); + // The fields every reader keys off keep their places above it + assert!(content.contains("**Time**:"), "{content}"); + assert!(content.find("**Author**").unwrap() < content.find("**Reason**").unwrap()); + + let entries = read_history(&board, "uuid").unwrap(); + assert_eq!(entries.len(), 1); + assert_eq!(entries[0].body, "reviewing → backlog"); + assert_eq!(entries[0].reason, "sent back: the first plan was wrong"); } /// The stamp leads the name and is fixed width, so the kind that follows it cannot @@ -464,7 +530,7 @@ mod tests { /// is what lets an old board be read without a migration. #[test] fn a_comment_file_is_shaped_as_it_always_was() { - let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00"); + let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00", ""); assert_eq!( content, "**Comment**\nA body\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n" @@ -535,10 +601,10 @@ mod tests { #[test] fn only_comments_are_counted() { let board = board(); - write_entry(&board, "uuid", Kind::Comment, "said", "claude").unwrap(); - write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude").unwrap(); - write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude").unwrap(); - write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude").unwrap(); + write_entry(&board, "uuid", Kind::Comment, "said", "claude", "").unwrap(); + write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude", "").unwrap(); + write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude", "").unwrap(); + write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude", "").unwrap(); assert_eq!(read_history(&board, "uuid").unwrap().len(), 4); assert_eq!(count_comments(&board, "uuid"), 1); @@ -618,6 +684,42 @@ mod tests { assert_eq!(format_history_with(&[], true), paint("No history yet.", Color::Grey, true)); } + /// The reason is the row's, so it renders indented under the row it explains and + /// before whatever entry follows, in both renderers — this is the one layout they + /// share. Paired with the pin above: an entry without a reason renders exactly as + /// it always did. + #[test] + fn a_reason_renders_indented_under_its_row() { + let entries = vec![ + parse_entry( + "20260824_120000_000000_status", + "**Status**\nreviewing → backlog\n\n**Author**: claude\n**Time**: 2026-08-24 \ + 12:00:00\n**Reason**: sent back, the first plan was wrong\n", + ), + parse_entry( + "20260824_120001_000000_comment", + "**Comment**\nAnd why.\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n", + ), + ]; + + let expected = format!( + "\n{}\n{}\n\n{} reviewing → backlog {}\n sent back, the first plan was wrong\n\n{}\n And why.\n", + paint("HISTORY", Color::Orange, true), + "─".repeat(20), + paint("status", Color::Orange, true), + paint("claude (2026-08-24 12:00:00)", Color::Cyan, true), + paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true), + ); + + assert_eq!(format_history_with(&entries, true), expected); + assert!( + format_history_with(&entries, false) + .contains("claude (2026-08-24 12:00:00)\n sent back, the first plan was wrong"), + "colour off lost the reason: {}", + format_history_with(&entries, false) + ); + } + /// Padded to the longest of the four, so every body starts in the same column /// however short the label above it is. #[test] diff --git a/src/main.rs b/src/main.rs index 42d11d5..7d9d9a1 100644 --- a/src/main.rs +++ b/src/main.rs @@ -57,9 +57,13 @@ fn main() -> Result<()> { let worklane_dir = find_worklane_dir(&start)?; cmd_show(&id, &worklane_dir) } - Some(Command::Mv { ticket, status, force, actor }) => { - cmd_mv(&ticket, status, force, &actor, &start) - } + Some(Command::Mv { + ticket, + status, + force, + actor, + reason, + }) => cmd_mv(&ticket, status, force, &actor, &reason, &start), Some(Command::Set(args)) => cmd_set(&args, &start), Some(Command::Append(args)) => cmd_append(&args, &start), Some(Command::Relate(args)) => cmd_relate(&args, &start), diff --git a/src/tui.rs b/src/tui.rs index 291967f..54b7898 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -5167,6 +5167,34 @@ mod tests { ); } + /// The board and `show` share one layout, so the reason a move carries renders + /// indented under the row it explains in the overlay too — attached to its + /// transition rather than sitting apart like a comment. + #[test] + fn the_detail_view_renders_a_reason_under_its_row() { + let dir = board_dir(); + let uuid = "11111111-0000-4000-8000-000000000000"; + write_ticket(&dir, "backlog", uuid, "First one", ""); + + let history = crate::history::history_dir(&dir, uuid); + std::fs::create_dir_all(&history).unwrap(); + std::fs::write( + history.join("20260821_120000_000000_status.md"), + "**Status**\nreviewing → backlog\n\n**Author**: claude\n**Time**: 2026-08-21 \ + 12:00:00\n**Reason**: sent back, wrong approach\n", + ) + .unwrap(); + + let mut board = one_board(&dir); + board.toggle_detail(); + let plain = board.detail.as_ref().expect("no detail").plain(); + + let expected = "status reviewing → backlog claude (2026-08-21 12:00:00)\n sent back, wrong \ + approach"; + assert!(plain.contains(expected), "{plain}"); + assert!(!plain.contains('\x1b'), "escapes reached the detail view: {plain:?}"); + } + /// The reported bug: the modal showed a description, criteria and a metadata /// table belonging to a ticket it never named. #[test] diff --git a/tests/cmd_mv.rs b/tests/cmd_mv.rs index 23cf3b3..315ba0d 100644 --- a/tests/cmd_mv.rs +++ b/tests/cmd_mv.rs @@ -1360,3 +1360,44 @@ fn un_discarding_drops_the_discard_stamp() { assert!(field(&content, "Discarded On").is_none(), "{content}"); assert!(field(&content, "Committed On").is_some(), "{content}"); } + +/// Prose takes a leading hyphen, so a reason that reads like a flag is stored as the +/// content it is rather than refused or swallowed. The cost of that bargain is that a +/// genuinely mistyped flag here lands in the log too. +#[test] +fn a_reason_takes_a_leading_hyphen_as_content() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket( + &worklane, + "backlog", + "Hyphen Reason", + "Prose trap.", + "bbbb2222", + "alice", + "_Not set_", + "", + ); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()) + .args([ + "mv", + "bbbb2222", + "--status", + "committed", + "--reason", + "-not-a-flag", + ]) + .assert() + .success(); + + let dir = worklane.join("history").join("bbbb2222"); + let entry = fs::read_dir(&dir) + .unwrap() + .filter_map(|e| e.ok()) + .map(|e| fs::read_to_string(e.path()).unwrap()) + .collect::>() + .join("\n"); + assert!(entry.contains("**Reason**: -not-a-flag\n"), "{entry:?}"); +} diff --git a/tests/history.rs b/tests/history.rs index 496f11f..92b2382 100644 --- a/tests/history.rs +++ b/tests/history.rs @@ -114,6 +114,94 @@ fn mv_writes_a_status_entry() { assert!(entry.contains("**Author**: claude"), "{entry:?}"); } +/// One file, one event, its explanation: `--reason` rides in the status entry that +/// records the transition it explains, as a field after **Time**, and `show` renders it +/// indented under the row rather than as a paragraph of its own. +#[test] +fn the_reason_travels_with_its_transition() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "reviewing"); + + run( + &temp, + &[ + "mv", + UUID, + "--status", + "backlog", + "-f", + "--reason", + "sent back: the first plan was wrong", + ], + ); + + let entry = only_entry(&worklane, "status"); + assert!(entry.starts_with("**Status**\nreviewing → backlog\n"), "{entry:?}"); + assert!( + entry.ends_with("**Reason**: sent back: the first plan was wrong\n"), + "{entry:?}" + ); + + let out = run(&temp, &["show", UUID]); + let stdout = String::from_utf8(out.stdout).unwrap(); + + let moved = stdout.find("reviewing → backlog").expect("the move is missing"); + let reason = stdout + .find("\n sent back: the first plan was wrong") + .expect("the reason is missing"); + // Attached means the very next line: nothing, not even a blank line, between. + assert!( + !stdout[moved..reason].contains('\n'), + "the reason is detached from its row:\n{stdout}" + ); +} + +/// The unusual moves are exactly the ones that need a why, so a refused one must not +/// log one either: the entry is written after the edit, and there was no edit. +#[test] +fn a_refused_move_writes_no_reason_either() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "reviewing"); + + let out = run( + &temp, + &[ + "mv", + UUID, + "--status", + "backlog", + "--reason", + "this move never happened", + ], + ); + assert_eq!(out.status.code(), Some(1)); + assert_eq!(entries(&worklane), vec![], "a refused move logged its reason"); +} + +/// Same for the move that changes nothing. +#[test] +fn a_no_op_move_writes_no_reason_either() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "committed"); + + let out = run( + &temp, + &[ + "mv", + UUID, + "--status", + "committed", + "--reason", + "nothing moved", + ], + ); + assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr)); + assert_eq!(entries(&worklane), vec![], "a no-op move logged its reason"); +} + #[test] fn chown_writes_an_owner_entry() { let temp = TempDir::new().unwrap();