(1845355) Order each status column by its entry stamp, and bump to 0.23.0

Every view read its rows out of `collect_ticket_items`, which sorts by
`by_priority_then_title` because it sees one directory and no status. That
is the right order for the backlog, where priority is the clock. Past the
backlog the question changes: committed asks what has waited longest,
reviewing what was handed over first, done what just landed. All four
columns answering the first question is why a finished p5 sat above the p1
nobody had read yet.

So each column takes its own order, through one `by_status_order` keyed on
the `Status` rather than four comparators at four call sites. Backlog
delegates to the comparator it already used. Committed sorts by
`Committed On` ascending and reviewing by `Submitted On` ascending, so the
longest wait is at the head where the reader picks next from; done sorts by
`Completed On` descending, newest first, the way a changelog reads.
Ascending twice and once descending is one rule said three ways: the head of
every column is what the reader acts on next.

A ticket carrying no stamp sinks below every stamped one in its column and
falls back to priority then title among its own kind, as do equal stamps --
`mv` writes whole seconds, so a tie is real. A missing time is unknown, not
ancient, and unknown must not claim the head of a queue ahead of a wait
somebody can point at. Reading absence as the epoch would have come free
from the comparison and put every ticket filed before f460853 first.

The comparison is a string comparison. `%Y-%m-%d %H:%M:%S` is lexicographic
in chronological order, the property `Due` already relies on, so nothing
parses a date at sort time. The stamps are read on the pass
`collect_ticket_items` already makes over each file, the rule `criteria` and
`tags` already hold, and never per comparison.

Both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`
take it, which is why those loops walk `Status::ALL` rather than
`status_dirs()`: the directory name does not say which stamp governs it. The
merge tab keeps priority then title outright and is pinned there -- it spans
statuses, so no single stamp governs it. `cmd_tags` is left alone; it counts
into a `BTreeMap` and never reads an order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-23 12:58:34 +02:00
co-authored by Claude Opus 5
parent eae411ab50
commit cbc20848f6
9 changed files with 621 additions and 39 deletions
+12 -9
View File
@@ -201,20 +201,23 @@ pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
let mut grouped = Vec::new();
for status in status_dirs() {
let status_path = worklane_dir.join(status);
// Over `Status::ALL` rather than the names, so each group can be put in its own
// column's order: a campaign's committed list answers what has waited longest for
// the same reason the board's column does.
for status in Status::ALL {
let status_path = worklane_dir.join(status.as_str());
let items = match status_path.exists() {
true => collect_ticket_items(&status_path)?,
false => Vec::new(),
};
grouped.push((
status,
items
.into_iter()
.filter(|item| item.campaign.as_deref() == Some(uuid))
.collect(),
));
let mut members: Vec<TicketItem> = items
.into_iter()
.filter(|item| item.campaign.as_deref() == Some(uuid))
.collect();
members.sort_by(|a, b| by_status_order(status, a, b));
grouped.push((status.as_str(), members));
}
Ok(grouped)
+27 -16
View File
@@ -63,8 +63,10 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
}
if let Some(status) = args.status {
let status = status.as_str();
let status_path = worklane_dir.join(status);
// The `Status` is kept alongside its name: the directory is joined from the
// name, and the order the column prints in is keyed on the status itself.
let name = status.as_str();
let status_path = worklane_dir.join(name);
if !status_path.exists() {
// The status itself is clap's to reject now, so reaching here means the
// board is missing a directory it should have rather than that the name was
@@ -72,19 +74,20 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
// alone.
return Err(anyhow!(
"No '{}' directory in {}. Every board has all four; creating it is enough.",
status,
name,
worklane_dir.display()
));
}
let items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
let mut items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
items.sort_by(|a, b| by_status_order(status, a, b));
if items.is_empty() {
println!("No tickets in '{}' status.", status);
println!("No tickets in '{}' status.", name);
return Ok(());
}
println!("Tickets in '{}' status:\n", status);
println!("Tickets in '{}' status:\n", name);
display_ticket_items(&items);
} else {
// List all statuses with their ticket counts
@@ -101,23 +104,27 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
println!(" [{}] {} {}", status.to_uppercase(), count, label);
}
// Show all tickets except done grouped by status
for status in &statuses {
if *status == DONE {
// Show all tickets except done grouped by status. Over `Status::ALL` rather
// than the names, because each column is ordered by its own entry stamp and the
// comparator is keyed on the status, not on the directory it was read from.
for status in Status::ALL {
if status.as_str() == DONE {
continue;
}
let status_path = worklane_dir.join(status);
let status_path = worklane_dir.join(status.as_str());
if !status_path.exists() || !fs::metadata(&status_path)?.is_dir() {
continue;
}
let items = match collect_ticket_items(&status_path) {
let mut items = match collect_ticket_items(&status_path) {
Ok(items) => filtered(items, priority_filter, uuid, tag),
Err(_) => continue,
};
items.sort_by(|a, b| by_status_order(status, a, b));
if items.is_empty() {
continue;
}
let status_header = color_text(&format!("[{}]", status.to_uppercase()), Color::Orange);
let status_header =
color_text(&format!("[{}]", status.as_str().to_uppercase()), Color::Orange);
println!("\n{}", status_header);
display_ticket_items(&items);
}
@@ -150,16 +157,20 @@ fn list_ids(
worklane_dir: &Path,
) -> Result<()> {
let statuses = match status {
Some(status) => vec![status.as_str()],
None => status_dirs(),
Some(status) => vec![status],
None => Status::ALL.to_vec(),
};
for status in statuses {
let status_path = worklane_dir.join(status);
let status_path = worklane_dir.join(status.as_str());
if !status_path.exists() {
continue;
}
for item in filtered(collect_ticket_items(&status_path)?, level, campaign, tag) {
// The same order the listing prints, so a completion and the board agree on
// which ticket is at the head of a column.
let mut items = filtered(collect_ticket_items(&status_path)?, level, campaign, tag);
items.sort_by(|a, b| by_status_order(status, a, b));
for item in items {
println!("{}\t{}", item.id, item.title);
}
}
+97 -3
View File
@@ -1157,12 +1157,14 @@ fn span_of(cell: Cell) -> Span<'static> {
fn columns_of(worklane_dir: &Path) -> (Vec<Column>, CampaignIndex) {
let campaigns = CampaignIndex::load(worklane_dir).unwrap_or_default();
let mut columns: Vec<Column> = status_dirs()
// Over `Status::ALL` rather than the names: each column is ordered by its own entry
// stamp, so the build needs the status itself and not just the directory to read.
let mut columns: Vec<Column> = Status::ALL
.into_iter()
.map(|status| {
// An absent or unreadable directory is an empty column, not a missing one:
// the four statuses are the shape of the board.
let cards = collect_ticket_items(worklane_dir.join(status))
let mut cards: Vec<Card> = collect_ticket_items(worklane_dir.join(status.as_str()))
.unwrap_or_default()
.into_iter()
.map(|ticket| Card {
@@ -1172,7 +1174,8 @@ fn columns_of(worklane_dir: &Path) -> (Vec<Column>, CampaignIndex) {
blocked: false,
})
.collect();
Column { status, cards }
cards.sort_by(|a, b| by_status_order(status, &a.ticket, &b.ticket));
Column { status: status.as_str(), cards }
})
.collect();
@@ -4530,6 +4533,97 @@ mod tests {
assert!(top.contains("backlog (1)"), "{top}");
}
/// The titles of one column, top to bottom, which is the order the reader acts on.
fn column_titles(board: &Board, at: usize) -> Vec<String> {
board.current().columns[at]
.cards
.iter()
.map(|card| card.ticket.title.clone())
.collect()
}
/// Each column is ordered by its own entry stamp, not by priority: committed is the
/// longest wait first, done is what just landed first. Every ticket here is a p2, so
/// the stamp is doing all of the work.
#[test]
fn a_column_is_ordered_by_the_stamp_the_ticket_entered_it_with() {
let dir = board_dir();
let stamp = |field: &str, at: &str| format!("- **{field}**: 2026-08-0{at} 09:00:00\n");
write_ticket(
&dir,
"committed",
"11111111-0000-4000-8000-000000000000",
"Waited",
&stamp("Committed On", "1"),
);
write_ticket(
&dir,
"committed",
"22222222-0000-4000-8000-000000000000",
"Fresh",
&stamp("Committed On", "3"),
);
write_ticket(
&dir,
"done",
"33333333-0000-4000-8000-000000000000",
"Older",
&stamp("Completed On", "1"),
);
write_ticket(
&dir,
"done",
"44444444-0000-4000-8000-000000000000",
"Newer",
&stamp("Completed On", "3"),
);
let board = boards(&[("only", &dir)]);
assert_eq!(column_titles(&board, 1), ["Waited", "Fresh"]);
assert_eq!(column_titles(&board, 3), ["Newer", "Older"]);
}
/// The merge spans statuses, so no single stamp governs it and it keeps priority then
/// title. Pinned on done, where the column order and the merge order disagree: the
/// board would put the newest first and the merge puts the p1 first.
#[test]
fn the_merge_keeps_priority_then_title_where_a_column_would_use_the_stamp() {
let (first, second) = (board_dir(), board_dir());
let card = |dir: &Path, uuid: &str, title: &str, level: u8, day: u8| {
let path = write_ticket(dir, "done", uuid, title, "");
let body = std::fs::read_to_string(&path)
.unwrap()
.replace("- **Priority**: 2", &format!("- **Priority**: {level}"))
.replace(
"- **Status**: done\n",
&format!("- **Completed On**: 2026-08-0{day} 09:00:00\n- **Status**: done\n"),
);
std::fs::write(&path, body).unwrap();
};
// Both on one board, so that board's own column can be read for the other
// order. The urgent one finished first, so stamp and priority disagree.
card(&first, "11111111-0000-4000-8000-000000000000", "Urgent", 1, 1);
card(&first, "22222222-0000-4000-8000-000000000000", "Later", 5, 3);
// A second board, which is what makes the merge tab exist at all.
card(&second, "33333333-0000-4000-8000-000000000000", "Other", 3, 2);
let mut board = boards(&[("alpha", &first), ("beta", &second)]);
assert_eq!(
column_titles(&board, 3),
["Urgent", "Other", "Later"],
"the merge sorted by stamp"
);
// The board the cards came from orders that column by the stamp, so the two
// really are two orders rather than one that happens to agree.
board.select_tab(1, SCREEN);
assert_eq!(column_titles(&board, 3), ["Later", "Urgent"]);
}
/// A tab per project, plus the merge, and the merge is where the view opens: it is
/// the reason to monitor several boards at once.
#[test]
+249 -5
View File
@@ -2506,8 +2506,8 @@ pub enum Status {
}
impl Status {
/// Every status, in flow order. The one list, which [`status_dirs`] and `mv` both
/// read rather than spelling the four names again.
/// Every status, in flow order. The one list, which [`status_dirs`], `mv` and every
/// caller of [`by_status_order`] read rather than spelling the four names again.
pub const ALL: [Status; 4] = [
Status::Backlog,
Status::Committed,
@@ -2663,6 +2663,48 @@ pub struct TicketItem {
/// The file this came from. The listing ignores it; the TUI opens it for the
/// detail view rather than resolving the ticket a second time.
pub path: std::path::PathBuf,
/// The time `mv` stamped on entering committed, or `None` for a ticket that has
/// never got that far.
///
/// Read here for the reason `criteria` is, and it is what its column is ordered by:
/// a comparator that read the file would re-read every ticket on every comparison,
/// where this pass reads each one once.
pub committed_on: Option<String>,
/// The same for reviewing.
pub submitted_on: Option<String>,
/// The same for done.
pub completed_on: Option<String>,
}
impl TicketItem {
/// The stamp the ticket entered a status with, which is what that column sorts on.
///
/// A slot per status rather than a lookup by field name, so a fifth status carrying
/// a stamp is a compile error here the way it is in [`Status::stamp_field`].
/// Backlog has none: nothing stamps it, and `Created At` is not an entry time, so
/// every ticket in that column answers `None` and the whole order is the fallback.
fn entry_stamp(&self, status: Status) -> Option<&str> {
match status {
Status::Backlog => None,
Status::Committed => self.committed_on.as_deref(),
Status::Reviewing => self.submitted_on.as_deref(),
Status::Done => self.completed_on.as_deref(),
}
}
}
/// The stamp a ticket carries for a status, or `None` for one it has not reached.
///
/// The field name comes off [`Status::stamp_field`], so what is read here cannot drift
/// from what `mv` writes. An absent field reads as `_Not set_` like every other, and a
/// stamp is machine-written so that spelling never appears as a value; both count as no
/// stamp rather than as a time.
fn parse_stamp(content: &str, status: Status) -> Option<String> {
let value = parse_ticket_field(content, status.stamp_field()?);
match is_unknown_value(&value) {
true => None,
false => Some(value),
}
}
/// The date part of a due value, for a view with only a corner to spend on it.
@@ -2824,6 +2866,9 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
uuid: parse_ticket_field(&content, "ID"),
blockers,
path: e.path(),
committed_on: parse_stamp(&content, Status::Committed),
submitted_on: parse_stamp(&content, Status::Reviewing),
completed_on: parse_stamp(&content, Status::Done),
})
})
.collect();
@@ -2832,11 +2877,13 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
Ok(items)
}
/// The order a status column is read in: priority first, title as the tiebreak.
/// The order the backlog is read in, and the tiebreak every other column falls back to:
/// priority first, title second.
///
/// Named and exported because the board's All tab merges several boards' columns into
/// one and has to land in the order the listing uses. A merge sorted a second way
/// would put a p1 below a p5 depending on which project it came from.
/// one and has to land in one order. A merge sorted a second way would put a p1 below a
/// p5 depending on which project it came from, and the merge spans statuses, so no
/// single stamp governs it.
pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
a.priority
.rank()
@@ -2844,6 +2891,39 @@ pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Order
.then_with(|| a.title.to_lowercase().cmp(&b.title.to_lowercase()))
}
/// The order one status column is read in, keyed on the status.
///
/// Priority is the clock in the backlog, and that column keeps exactly the order it has
/// always printed. Past the backlog the question changes: committed asks what has waited
/// longest, reviewing what was handed over first, done what just landed. The head of
/// every column is therefore what the reader acts on next, which is ascending by entry
/// stamp in committed and reviewing and descending in done, the way a changelog reads.
///
/// A ticket with no stamp sinks below every stamped one in its column. A missing time is
/// unknown, not ancient, and unknown must not claim the head of a queue ahead of a wait
/// somebody can point at. Reading absence as the epoch would come free from the string
/// comparison and put every legacy ticket first on data nothing verified.
///
/// The comparison is a string comparison. The stamp format is `%Y-%m-%d %H:%M:%S`, where
/// lexicographic order is chronological order, the same property `Due` already relies
/// on, so there is no date parsing at sort time. Equal stamps happen, `mv` writes whole
/// seconds, and they fall through to priority and title like everything else.
pub fn by_status_order(status: Status, a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
let by_stamp = match (a.entry_stamp(status), b.entry_stamp(status)) {
(Some(left), Some(right)) => match status {
Status::Done => right.cmp(left),
_ => left.cmp(right),
},
(Some(_), None) => std::cmp::Ordering::Less,
(None, Some(_)) => std::cmp::Ordering::Greater,
// Both unstamped, which is every ticket in the backlog: the fallback is the
// whole order there rather than a tiebreak.
(None, None) => std::cmp::Ordering::Equal,
};
by_stamp.then_with(|| by_priority_then_title(a, b))
}
#[cfg(test)]
mod tests {
use super::*;
@@ -3521,6 +3601,170 @@ mod tests {
);
}
/// A listed ticket with only the fields the column order reads: its title, its
/// priority and the stamp for the status being sorted.
fn listed(title: &str, level: u8, status: Status, stamp: Option<&str>) -> TicketItem {
let stamp = stamp.map(|value| value.to_string());
TicketItem {
title: title.to_string(),
owner: NOT_SET.to_string(),
due: NOT_SET.to_string(),
id: "0000000".to_string(),
created: String::new(),
priority: Priority::Level(level),
criteria: None,
campaign: None,
tags: Vec::new(),
uuid: NOT_SET.to_string(),
blockers: Vec::new(),
path: std::path::PathBuf::new(),
committed_on: match status {
Status::Committed => stamp.clone(),
_ => None,
},
submitted_on: match status {
Status::Reviewing => stamp.clone(),
_ => None,
},
completed_on: match status {
Status::Done => stamp,
_ => None,
},
}
}
/// Sorted the way the column is read, titles out, so a case reads as the order it
/// asserts rather than as a pair of comparisons.
fn ordered(status: Status, mut items: Vec<TicketItem>) -> Vec<String> {
items.sort_by(|a, b| by_status_order(status, a, b));
items.into_iter().map(|item| item.title).collect()
}
/// The backlog is the one column priority still governs, and it prints exactly what
/// it always has: the stamps a ticket carries from an earlier trip through the flow
/// do not reach it, because backlog has no stamp of its own to sort on.
#[test]
fn the_backlog_keeps_priority_then_title() {
let items = vec![
listed("zebra", 5, Status::Backlog, None),
listed("alpha", 1, Status::Backlog, None),
listed("beta", 1, Status::Backlog, None),
];
assert_eq!(ordered(Status::Backlog, items), ["alpha", "beta", "zebra"]);
}
/// Committed and reviewing are queues: the head is what has waited longest, which is
/// where the reader picks next from.
#[test]
fn committed_and_reviewing_list_the_oldest_stamp_first() {
for status in [Status::Committed, Status::Reviewing] {
let items = vec![
listed("newest", 1, status, Some("2026-08-03 09:00:00")),
listed("oldest", 5, status, Some("2026-08-01 09:00:00")),
listed("middle", 1, status, Some("2026-08-02 09:00:00")),
];
assert_eq!(ordered(status, items), ["oldest", "middle", "newest"], "{status:?}");
}
}
/// Done reads like a changelog: what just landed is at the top, and priority no
/// longer decides anything about finished work.
#[test]
fn done_lists_the_newest_stamp_first() {
let items = vec![
listed("first", 1, Status::Done, Some("2026-08-01 09:00:00")),
listed("last", 5, Status::Done, Some("2026-08-03 09:00:00")),
listed("middle", 1, Status::Done, Some("2026-08-02 09:00:00")),
];
assert_eq!(ordered(Status::Done, items), ["last", "middle", "first"]);
}
/// A missing stamp is unknown, not ancient. Reading absence as the epoch would come
/// free from the string comparison and hand the head of the queue to every legacy
/// ticket, so it sinks instead, in both directions.
#[test]
fn a_ticket_with_no_stamp_sorts_below_every_stamped_one() {
for status in [Status::Committed, Status::Reviewing, Status::Done] {
let items = vec![
listed("unstamped", 1, status, None),
listed("stamped", 5, status, Some("2026-08-01 09:00:00")),
];
assert_eq!(ordered(status, items), ["stamped", "unstamped"], "{status:?}");
}
}
/// `mv` writes whole seconds, so two moves in the same second is a real tie rather
/// than a hypothetical one, and it falls through to the order the backlog uses.
#[test]
fn equal_stamps_fall_back_to_priority_then_title() {
let same = Some("2026-08-01 09:00:00");
let items = vec![
listed("zebra", 1, Status::Committed, same),
listed("beta", 3, Status::Committed, same),
listed("alpha", 3, Status::Committed, same),
];
assert_eq!(ordered(Status::Committed, items), ["zebra", "alpha", "beta"]);
}
/// Two unstamped tickets in one column are ordered among themselves the way the
/// backlog is, rather than left in whatever order the directory handed them back.
#[test]
fn unstamped_tickets_are_ordered_among_themselves_by_priority_then_title() {
let items = vec![
listed("zebra", 1, Status::Done, None),
listed("beta", 3, Status::Done, None),
listed("alpha", 3, Status::Done, None),
];
assert_eq!(ordered(Status::Done, items), ["zebra", "alpha", "beta"]);
}
/// The stamps come off the pass that builds the listing, not off a second read at
/// comparison time, which is what makes an ordered column cost one read per file.
#[test]
fn collect_ticket_items_reads_the_stamps_the_order_sorts_on() {
let dir = std::env::temp_dir().join(format!("worklane-stamps-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&dir).unwrap();
fs::write(
dir.join("aaaa_walked.md"),
"# Walked\n\n## Metadata\n\n\
- **ID**: aaaa\n\
- **Committed On**: 2026-08-01 09:00:00\n\
- **Submitted On**: 2026-08-02 09:00:00\n\
- **Completed On**: 2026-08-03 09:00:00\n\
- **Status**: done\n",
)
.unwrap();
fs::write(
dir.join("bbbb_fresh.md"),
"# Fresh\n\n## Metadata\n\n- **ID**: bbbb\n- **Status**: backlog\n",
)
.unwrap();
let items = collect_ticket_items(&dir).unwrap();
let walked = items.iter().find(|item| item.title == "Walked").unwrap();
assert_eq!(walked.committed_on.as_deref(), Some("2026-08-01 09:00:00"));
assert_eq!(walked.submitted_on.as_deref(), Some("2026-08-02 09:00:00"));
assert_eq!(walked.completed_on.as_deref(), Some("2026-08-03 09:00:00"));
// Absent reads as no stamp rather than as the `_Not set_` every other field
// falls back to, so the order sinks it instead of comparing that text.
let fresh = items.iter().find(|item| item.title == "Fresh").unwrap();
assert_eq!(fresh.committed_on, None);
assert_eq!(fresh.submitted_on, None);
assert_eq!(fresh.completed_on, None);
fs::remove_dir_all(&dir).unwrap();
}
/// Removal is scoped to the section for the same reason the write is: a description
/// quoting a field marker is prose, and rewriting it would corrupt the ticket text
/// while leaving the real field in place.