(a6023e2) Stamp the time a ticket entered its status, and bump to 0.17.1

mv writes Committed On, Submitted On or Completed On for the status it
enters, so the board answers how long a ticket has been where it is
without guessing from file mtimes.

The three are mutually exclusive: entering stamps, leaving removes and
re-entering restamps, so a backward move under -f leaves no stale
Completed On behind. These fields are current state, like Status itself;
the trail of how the ticket got there belongs to the history log.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-22 20:31:53 +02:00
co-authored by Claude Opus 5
parent 373ba519b3
commit 139c9b012f
9 changed files with 454 additions and 8 deletions
+199 -4
View File
@@ -1064,6 +1064,35 @@ fn set_metadata_line(
if found { Some(updated) } else { None }
}
/// Drop one field from the Metadata section, leaving every other line untouched.
///
/// Scoped to the section for the same reason as [`set_metadata_line`], and shaped like
/// it: nothing means there was no such field, so a caller that removes a field a ticket
/// never carried leaves the content exactly as it found it rather than rewriting it
/// into an identical string.
fn remove_metadata_line(content: &str, field: &str) -> Option<String> {
let prefix = format!("**{}**:", field);
let mut updated = String::with_capacity(content.len());
let mut in_metadata = false;
let mut found = false;
for line in content.lines() {
if line.starts_with("## ") {
in_metadata = is_metadata_heading(line);
}
if in_metadata && !found && metadata_field_body(line).starts_with(&prefix) {
found = true;
continue;
}
updated.push_str(line);
updated.push('\n');
}
if found { Some(updated) } else { None }
}
pub fn set_status_field(content: &str, target_status: &str, title: &str) -> Result<String> {
set_metadata_line(content, "Status", target_status, is_status_line).ok_or_else(|| {
anyhow!(
@@ -1136,20 +1165,26 @@ pub fn parse_tags(content: &str) -> Vec<String> {
.collect()
}
/// The metadata fields in the order `add` writes them, with `Campaign` in its place
/// among them.
/// The metadata fields in the order `add` writes them, with the fields no ticket is
/// born with in their places among them.
///
/// The anchor list for inserting a field the file does not have yet, exactly as
/// [`SECTION_ORDER`] is for a missing section. Campaign sits beside Status because the
/// two answer the same kind of question, where the ticket belongs rather than what it
/// is, and Status stays last, which is where every file already keeps it.
const METADATA_ORDER: [&str; 8] = [
/// is, and Status stays last, which is where every file already keeps it. The three
/// stamps follow `Created At`, since they answer the same question it does about a
/// later moment, and they are in flow order for a reader who sees one after another
/// across a board.
const METADATA_ORDER: [&str; 11] = [
"ID",
"Priority",
"Tags",
"Due",
"Owner",
"Created At",
COMMITTED_ON_FIELD,
SUBMITTED_ON_FIELD,
COMPLETED_ON_FIELD,
CAMPAIGN_FIELD,
"Status",
];
@@ -1228,6 +1263,52 @@ fn insert_metadata_field(content: &str, field: &str, value: &str, title: &str) -
Ok(join_lines(&out))
}
// The metadata fields `mv` stamps with the time a ticket entered a status. Backlog has
// none: a ticket is filed there, and `Created At` already records when, so a fourth
// field would say the same thing for every ticket that has never moved.
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.
///
/// 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 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<String> {
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;
}
let Some(field) = status.stamp_field() else {
continue;
};
if let Some(updated) = remove_metadata_line(&content, field) {
content = updated;
}
}
match target.stamp_field() {
// Inserted on demand, the way Campaign is: every ticket written before these
// fields existed carries none of them.
Some(field) => set_or_insert_metadata_field(&content, field, now, title),
None => Ok(content),
}
}
/// Rewrite the title heading, the first `# ` line in the file.
///
/// `## ` headings do not match: the second character has to be a space.
@@ -2190,6 +2271,20 @@ impl Status {
Status::Done,
];
/// The field `mv` stamps on entering this status, for the three that have one.
///
/// Derived from the status rather than spelled at the call site, so the mapping is
/// in one place and a fifth status either brings its own stamp or explicitly has
/// none.
pub const fn stamp_field(self) -> Option<&'static str> {
match self {
Status::Backlog => None,
Status::Committed => Some(COMMITTED_ON_FIELD),
Status::Reviewing => Some(SUBMITTED_ON_FIELD),
Status::Done => Some(COMPLETED_ON_FIELD),
}
}
/// The directory name, which is also what clap accepts and what the `Status` field
/// holds. A `const fn` so [`DONE`] can be defined from it.
pub const fn as_str(self) -> &'static str {
@@ -3059,6 +3154,106 @@ 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.
#[test]
fn entering_a_status_stamps_its_field_and_clears_the_rest() {
let content = with_metadata(
"- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: committed\n",
);
let updated =
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}");
}
/// 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.
#[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",
);
let updated =
set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap();
assert!(!updated.contains("**Completed On**"), "{updated}");
assert!(!updated.contains("2026-08-22 10:11:12"), "{updated}");
assert!(updated.contains("- **ID**: abc\n- **Status**: done\n"), "{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() {
let content = with_metadata(
"- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: backlog\n",
);
let updated =
set_status_stamp(&content, Status::Committed, "2026-08-22 10:11:12", "T").unwrap();
assert_eq!(updated.matches("**Committed On**:").count(), 1, "{updated}");
assert!(!updated.contains("2026-08-01 09:00:00"), "{updated}");
}
/// Against METADATA_ORDER, like Campaign: after Created At, which answers the same
/// kind of question, and never past Status, which every file keeps last.
#[test]
fn a_stamp_is_inserted_in_its_place_on_a_ticket_that_predates_the_field() {
let content = with_metadata(
"- **ID**: abc\n\
- **Created At**: 2026-08-01 09:00:00\n\
- **Campaign**: c-uuid\n\
- **Status**: reviewing\n",
);
let updated =
set_status_stamp(&content, Status::Done, "2026-08-22 10:11:12", "T").unwrap();
assert!(
updated.contains(
"- **Created At**: 2026-08-01 09:00:00\n\
- **Completed On**: 2026-08-22 10:11:12\n\
- **Campaign**: c-uuid\n\
- **Status**: reviewing\n"
),
"{updated}"
);
}
/// 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.
#[test]
fn a_marker_in_the_description_is_not_the_field_being_removed() {
let content = "# T\n\n## Description\n- **Committed On**: not a field\n\n\
## Metadata\n\n- **ID**: abc\n- **Status**: backlog\n";
let updated =
set_status_stamp(content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap();
assert!(updated.contains("- **Committed On**: not a field"), "{updated}");
}
/// Nothing to remove is not a rewrite: the content comes back byte for byte, which
/// is what keeps a move that stamps nothing from touching the file's shape.
#[test]
fn removing_a_field_the_ticket_does_not_carry_leaves_the_content_alone() {
let content = with_metadata("- **ID**: abc\n- **Status**: backlog\n");
assert_eq!(remove_metadata_line(&content, COMPLETED_ON_FIELD), None);
assert_eq!(
set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap(),
content
);
}
#[test]
fn a_campaign_field_that_is_unset_or_absent_reads_as_no_campaign() {
assert_eq!(parse_campaign(&with_metadata("- **ID**: abc\n")), None);