diff --git a/AGENTS.md b/AGENTS.md index 4869d8e..0806e19 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ - Filenames: `_.md` - The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand - Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last -- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they are mutually exclusive: entering a status writes its field, leaving removes it, re-entering restamps. So a ticket carries at most one, the one for the status it is sitting in, and a backward move under `-f` leaves no stale `Completed On` behind. They are current state, like `Status` itself; the trail of how the ticket got there is d4ce964's job and must not be grown here. `backlog` has no stamp, `Created At` already answers for it +- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it - Format: `**Field Name**: value` - Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata` - A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign diff --git a/Cargo.lock b/Cargo.lock index 67a8fc8..d69fd5e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.21.1" +version = "0.22.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 5c12e0d..154ae84 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.21.1" +version = "0.22.0" edition = "2024" [dependencies] diff --git a/src/util.rs b/src/util.rs index f7ba154..4053d5a 100644 --- a/src/util.rs +++ b/src/util.rs @@ -1364,28 +1364,38 @@ pub const COMMITTED_ON_FIELD: &str = "Committed On"; pub const SUBMITTED_ON_FIELD: &str = "Submitted On"; pub const COMPLETED_ON_FIELD: &str = "Completed On"; -/// Stamp the field of the status being entered and drop the other two. +/// Stamp the field of the status being entered and drop the ones after it. /// -/// A stamp is present exactly while the ticket sits in its status, so the three are -/// mutually exclusive: entering writes one, leaving removes it, and re-entering -/// restamps rather than keeping the first value. That is what keeps a ticket moved -/// backward under `-f` from carrying a `Completed On` for work it has undone, and it is -/// the line between these fields and d4ce964's history log. Metadata carries current -/// state, which is why `Status` is a field at all; the trail of how the ticket got here -/// belongs to the log, and a stamp left behind would be a second copy of that job. +/// The stamps accumulate down the flow rather than being mutually exclusive, so a +/// ticket that has walked the whole way carries `Created At`, `Committed On`, +/// `Submitted On` and `Completed On` side by side and the journey behind it is legible. +/// Presence therefore means the ticket got that far and has not been sent back past it, +/// not that it is sitting there now; `Status` is what says where it is. +/// +/// One arrival rule covers both directions. A backward move truncates the journey at +/// the target, so `done` back to `reviewing` drops `Completed On` and keeps the two +/// before it, and anything back to `backlog` drops all three. A forward skip under `-f` +/// has nothing after it to clear, so `backlog` straight to `done` stamps `Completed On` +/// alone and leaves the stages it jumped over unwritten rather than fabricated. +/// Re-entering restamps rather than keeping the earlier value. +/// +/// This is still not d4ce964's history log. These fields answer how far and when, once +/// per stage; every status change, every owner and every tag along the way is the log's +/// job and must not be grown here. `backlog` has no stamp, `Created At` answers for it. /// /// The time comes in as a string rather than being read here, so the caller stamps the /// same moment it reports and a test can pin the value. pub fn set_status_stamp(content: &str, target: Status, now: &str, title: &str) -> Result { let mut content = content.to_string(); - // Every status but the target, so a skipping move under `-f` clears the stamps of - // the stages it jumped over as well as the one it left. - for status in Status::ALL { - if status == target { - continue; - } - + // Every status after the target, off the flow order `Status::ALL` already holds + // rather than a case per move, so arrival alone decides what is cleared and a + // backward move and a skip are the same rule. + for status in Status::ALL + .iter() + .skip_while(|status| **status != target) + .skip(1) + { let Some(field) = status.stamp_field() else { continue; }; @@ -3403,10 +3413,10 @@ mod tests { assert!(error.to_string().contains("Campaign"), "{error}"); } - /// The one stamp the target status carries, and nothing of the others: the fields - /// are current state, not a record of every stage the ticket has been through. + /// The stamp of the status being entered, added to what the ticket already carries: + /// the fields accumulate down the flow, so the stages behind it stay readable. #[test] - fn entering_a_status_stamps_its_field_and_clears_the_rest() { + fn entering_a_status_stamps_its_field_and_keeps_the_ones_before_it() { let content = with_metadata( "- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: committed\n", ); @@ -3415,25 +3425,64 @@ mod tests { set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap(); assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}"); - assert!(!updated.contains("**Committed On**"), "{updated}"); + assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}"); } - /// Backlog has no stamp of its own, so a backward move under `-f` leaves the ticket - /// carrying none rather than a Completed On for work it has undone. + /// Arrival truncates the journey at the target, so the stage the ticket has been + /// sent back out of is dropped and the ones it still got through are not. + #[test] + fn arriving_removes_the_stamps_of_the_statuses_after_the_target() { + let content = with_metadata( + "- **ID**: abc\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", + ); + + let updated = + set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap(); + + assert!(!updated.contains("**Completed On**"), "{updated}"); + assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}"); + assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}"); + } + + /// Backlog has no stamp of its own and every status follows it, so a ticket forced + /// all the way back carries none of the three rather than a trail it has undone. #[test] fn moving_back_to_backlog_leaves_no_stamp_behind() { let content = with_metadata( - "- **ID**: abc\n- **Completed On**: 2026-08-01 09:00:00\n- **Status**: done\n", + "- **ID**: abc\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", ); let updated = set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap(); - assert!(!updated.contains("**Completed On**"), "{updated}"); + for field in [COMMITTED_ON_FIELD, SUBMITTED_ON_FIELD, COMPLETED_ON_FIELD] { + assert!(!updated.contains(&format!("**{}**", field)), "{updated}"); + } assert!(!updated.contains("2026-08-22 10:11:12"), "{updated}"); assert!(updated.contains("- **ID**: abc\n- **Status**: done\n"), "{updated}"); } + /// A skip stamps the target and nothing else. The stages it jumped over are left + /// unwritten rather than given a time the ticket never spent there. + #[test] + fn a_forward_skip_stamps_only_the_status_it_lands_in() { + let content = with_metadata("- **ID**: abc\n- **Status**: backlog\n"); + + let updated = set_status_stamp(&content, Status::Done, "2026-08-22 10:11:12", "T").unwrap(); + + assert!(updated.contains("- **Completed On**: 2026-08-22 10:11:12"), "{updated}"); + assert!(!updated.contains("**Committed On**"), "{updated}"); + assert!(!updated.contains("**Submitted On**"), "{updated}"); + } + /// Re-entry is the time of the move that brought it back, not the first one. #[test] fn re_entering_a_status_restamps_rather_than_keeping_the_earlier_value() { diff --git a/tests/cmd_mv.rs b/tests/cmd_mv.rs index 4f59b37..0f24501 100644 --- a/tests/cmd_mv.rs +++ b/tests/cmd_mv.rs @@ -923,35 +923,89 @@ fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String { fs::read_to_string(worklane.join(status).join(filename)).unwrap() } -/// One field per status, written with the time of the move, and only the current one: -/// the stamps are where the ticket is now, not the trail of how it got there. +/// One field per status, written with the time of the move and added to the ones +/// already there: walking the flow leaves the whole journey on the ticket. #[test] fn mv_stamps_the_field_of_the_status_it_enters() { let temp = TempDir::new().unwrap(); let worklane = setup_worklane(&temp); let filename = stamped_ticket(&worklane, "backlog"); - for (status, stamp, cleared) in [ - ("committed", "Committed On", "Submitted On"), - ("reviewing", "Submitted On", "Committed On"), - ("done", "Completed On", "Submitted On"), + // The fixture predates Created At as well as the stamps, and the four reading as + // one block is the point, so it is seeded rather than asserted around. + let path = worklane.join("backlog").join(&filename); + let seeded = fs::read_to_string(&path) + .unwrap() + .replace("- **Status**:", "- **Created At**: 2026-08-01 09:00:00\n- **Status**:"); + fs::write(&path, seeded).unwrap(); + + let mut carried: Vec<&str> = Vec::new(); + + for (status, stamp) in [ + ("committed", "Committed On"), + ("reviewing", "Submitted On"), + ("done", "Completed On"), ] { let out = move_ticket(&temp, "cccc3333", status, false); assert!(out.status.success(), "{:?}", out); + carried.push(stamp); let content = ticket_at(&worklane, status, &filename); - let value = field(&content, stamp) - .unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}")); - assert!(is_timestamp(&value), "{stamp} reads '{value}'"); - assert_eq!(field(&content, cleared), None, "{content}"); + for stamp in &carried { + let value = field(&content, stamp) + .unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}")); + assert!(is_timestamp(&value), "{stamp} reads '{value}'"); + } } + + // The four side by side and in flow order, which is what a reader asking when this + // was filed, picked up, handed over and finished gets one answer each from. + let content = ticket_at(&worklane, "done", &filename); + let block: Vec<&str> = content + .lines() + .filter_map(|line| line.strip_prefix("- **")) + .filter_map(|line| line.split("**:").next()) + .skip_while(|name| *name != "Created At") + .collect(); + + assert_eq!( + block, + [ + "Created At", + "Committed On", + "Submitted On", + "Completed On", + "Status" + ], + "{content}" + ); } -/// Backlog has no stamp of its own, so a ticket forced back to it carries none at all -/// rather than a Completed On for work that has been undone. +/// Arrival clears what comes after it and nothing before, so a ticket sent back out of +/// done keeps the stages it did get through. #[test] -fn mv_removes_the_stamp_of_the_status_it_leaves() { +fn mv_removes_the_stamps_of_the_statuses_after_the_one_it_enters() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = stamped_ticket(&worklane, "backlog"); + + for status in ["committed", "reviewing", "done"] { + move_ticket(&temp, "cccc3333", status, false); + } + + move_ticket(&temp, "cccc3333", "reviewing", true); + + let content = ticket_at(&worklane, "reviewing", &filename); + assert_eq!(field(&content, "Completed On"), None, "{content}"); + assert!(field(&content, "Committed On").is_some(), "{content}"); + assert!(field(&content, "Submitted On").is_some(), "{content}"); +} + +/// Backlog has no stamp of its own and every status follows it, so a ticket forced back +/// to it carries none at all rather than a Completed On for work that has been undone. +#[test] +fn mv_back_to_backlog_removes_all_three_stamps() { let temp = TempDir::new().unwrap(); let worklane = setup_worklane(&temp); let filename = stamped_ticket(&worklane, "backlog"); @@ -968,6 +1022,42 @@ fn mv_removes_the_stamp_of_the_status_it_leaves() { } } +/// A skip stamps where it lands and leaves the stages it jumped unwritten: an absent +/// field says the ticket never got that far, and inventing one would say it did. +#[test] +fn mv_skipping_forward_stamps_only_the_target() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = stamped_ticket(&worklane, "backlog"); + + move_ticket(&temp, "cccc3333", "done", true); + + let content = ticket_at(&worklane, "done", &filename); + assert!(field(&content, "Completed On").is_some(), "{content}"); + assert_eq!(field(&content, "Committed On"), None, "{content}"); + assert_eq!(field(&content, "Submitted On"), None, "{content}"); +} + +/// The three are `mv`'s alone. Nothing that edits a ticket by hand offers a way to +/// write one or take one away, so a stamp is always the record of a real move. Pinned +/// so the omission stays a decision rather than becoming an oversight somebody fills in. +#[test] +fn no_other_command_can_write_or_clear_a_stamp() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + for command in ["add", "set", "append", "chown"] { + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()).args([command, "--help"]); + let out = cmd.assert().get_output().clone(); + let help = String::from_utf8_lossy(&out.stdout).to_lowercase(); + + for flag in ["committed-on", "submitted-on", "completed-on", "stamp"] { + assert!(!help.contains(flag), "{command} --help names {flag}: {help}"); + } + } +} + /// Re-entry is the time of the move that brought the ticket back, not the first one. #[test] fn mv_restamps_a_status_the_ticket_is_re_entering() {