(1f1b321) Record a move's reason in its history entry, and bump to 0.31.2

This commit is contained in:
Ansho Rei
2026-08-25 10:38:04 +02:00
parent 60b43a682e
commit 102e9c889b
10 changed files with 310 additions and 22 deletions
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.31.1"
version = "0.31.2"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.31.1"
version = "0.31.2"
edition = "2024"
[dependencies]
+5
View File
@@ -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
```
+5
View File
@@ -230,6 +230,11 @@ pub enum Command {
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
/// 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<String>,
},
/// Replace fields on an existing ticket
+16 -1
View File
@@ -607,10 +607,20 @@ pub fn cmd_mv(
target: Status,
force: bool,
actor: &Option<String>,
reason: &Option<String>,
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::<Vec<_>>().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(&current_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!(
+118 -16
View File
@@ -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<String> {
/// 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<String> {
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<Cell> {
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<Cell> {
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]
+7 -3
View File
@@ -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),
+28
View File
@@ -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]
+41
View File
@@ -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::<Vec<_>>()
.join("\n");
assert!(entry.contains("**Reason**: -not-a-flag\n"), "{entry:?}");
}
+88
View File
@@ -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();