One flat list ordered by title put the completed campaigns among the open ones forever. The tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it, and nothing in the picker helped find one. The rows are now two sections, open above completed, with completed by Created At newest first and truncated to a couple behind a grey line naming how many older ones are hidden. `/` starts a query, the key that already searches the board's cards, filtering case insensitively on short id, codename and title, and a query turns the truncation off: the campaign a reader is searching for is exactly the one it hid. `picker_list` is the one place that decides what a row is, so `Picker::row` counts drawn rows and `stepped_picker_row` walks past the headings and the truncation line rather than stopping on one. The highlight is placed by uuid, the answer `Tab::campaign` already gives for the filter, so typing, clearing the query and a tick that finishes a campaign all move it with its campaign instead of leaving it at a number that now names another. Every campaign's standing is settled at reload, counted by `standings_of` in one pass over the cards the reload already holds rather than the walk per campaign `campaign ls` pays. `Tab::standing` goes with it: the frame reads the row's, since two counts of one number are two numbers free to drift. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
320 lines
12 KiB
Rust
320 lines
12 KiB
Rust
//! Campaigns: the container for tickets that have to be finished together.
|
|
//!
|
|
//! A campaign is a file of its own under `.worklane/campaigns/`, holding a title, a
|
|
//! description and metadata. It has no status directory and never sits in one. Its
|
|
//! state is derived instead: open until every member is done. Deriving it means there
|
|
//! is no such thing as a done campaign holding an open ticket, and no second
|
|
//! forward-only ruleset to reason about beside `mv`'s.
|
|
//!
|
|
//! Membership is one field on the *member*, `Campaign` in the ticket Metadata, written
|
|
//! only by `assign`. The member list is deliberately not stored on the campaign: that
|
|
//! would put membership in two places, and would make one file that every assignment
|
|
//! edits, which is contended the moment two agents share a board.
|
|
|
|
use anyhow::{Result, anyhow};
|
|
use std::fs;
|
|
use std::path::{Path, PathBuf};
|
|
|
|
use crate::util::*;
|
|
|
|
/// Where campaigns live, beside the status directories rather than among them.
|
|
pub const CAMPAIGNS_DIR: &str = "campaigns";
|
|
|
|
pub fn campaigns_dir(worklane_dir: &Path) -> PathBuf {
|
|
worklane_dir.join(CAMPAIGNS_DIR)
|
|
}
|
|
|
|
/// The campaigns directory, created if the board predates it.
|
|
///
|
|
/// `init` writes it for a new board, but every board made before campaigns existed has
|
|
/// none, and refusing to file a campaign there would mean a `worklane init` over a live
|
|
/// board just to get a directory.
|
|
pub fn ensure_campaigns_dir(worklane_dir: &Path) -> Result<PathBuf> {
|
|
let dir = campaigns_dir(worklane_dir);
|
|
|
|
fs::create_dir_all(&dir).map_err(|e| anyhow!("Could not create {}: {}", dir.display(), e))?;
|
|
|
|
Ok(dir)
|
|
}
|
|
|
|
/// A campaign as it comes off disk.
|
|
pub struct Campaign {
|
|
pub uuid: String,
|
|
pub title: String,
|
|
/// The word the campaign is called by, or `None` for one filed without a codename.
|
|
///
|
|
/// Read here rather than parsed at each call site for the reason the title is: the
|
|
/// board draws it on every card that names this campaign, and the picker draws it on
|
|
/// every row, so it comes off the one read of the directory.
|
|
pub codename: Option<String>,
|
|
pub content: String,
|
|
}
|
|
|
|
/// The campaigns directory as [`resolve_in`] takes it.
|
|
///
|
|
/// The name is empty because a campaign has no status: it is what makes the ambiguity
|
|
/// listing print an id and a title with no bracket after it.
|
|
fn campaign_paths(worklane_dir: &Path) -> Vec<(String, PathBuf)> {
|
|
vec![(String::new(), campaigns_dir(worklane_dir))]
|
|
}
|
|
|
|
/// A campaign by the same three tiers a ticket resolves by, scoped to its own
|
|
/// directory.
|
|
///
|
|
/// The tiers are [`resolve_in`]'s, not a second copy: a campaign is addressed the way
|
|
/// everything else here is, and two resolvers would be two sets of precedence rules to
|
|
/// keep in step.
|
|
pub fn resolve_campaign(search: &str, worklane_dir: &Path) -> Result<Campaign> {
|
|
let mut matches = resolve_in(search, &campaign_paths(worklane_dir))?;
|
|
|
|
if matches.is_empty() {
|
|
return Err(anyhow!("No campaign found matching '{}'", search));
|
|
}
|
|
|
|
if matches.len() > 1 {
|
|
return Err(ambiguous("campaign", search, &matches));
|
|
}
|
|
|
|
let found = matches.remove(0);
|
|
let uuid = parse_ticket_field(&found.content, "ID");
|
|
|
|
if uuid.trim().is_empty() || is_unknown_value(&uuid) {
|
|
return Err(anyhow!(
|
|
"Campaign '{}' has no ID field, so nothing can be assigned to it",
|
|
found.title
|
|
));
|
|
}
|
|
|
|
Ok(Campaign {
|
|
codename: parse_codename(&found.content),
|
|
uuid,
|
|
title: found.title,
|
|
content: found.content,
|
|
})
|
|
}
|
|
|
|
/// The title of the campaign a search names, for a caller that only needs to say so.
|
|
///
|
|
/// Used by `resolve_ticket` to explain a search that names a campaign rather than a
|
|
/// ticket. Deliberately swallows both failures: nothing matched and too much matched
|
|
/// both mean "this is not the explanation", and an error here would replace a clear
|
|
/// "no ticket found" with a complaint about a directory the caller never mentioned.
|
|
pub fn campaign_named(search: &str, worklane_dir: &Path) -> Option<String> {
|
|
resolve_campaign(search, worklane_dir)
|
|
.ok()
|
|
.map(|campaign| campaign.title)
|
|
}
|
|
|
|
/// Every campaign on the board, read in one pass.
|
|
///
|
|
/// One pass for the same reason [`RelationIndex`] takes one: rendering a ticket's
|
|
/// Campaign field or listing the campaigns both need every one of them, and a lookup
|
|
/// per ticket would read the directory once per row.
|
|
///
|
|
/// `Default` is the empty index, which is what a board whose campaigns directory cannot be
|
|
/// read has: it still draws, with no campaign on any card. A *missing* directory is already
|
|
/// not an error, per [`CampaignIndex::load`]; this is for the unreadable one.
|
|
#[derive(Default)]
|
|
pub struct CampaignIndex {
|
|
campaigns: Vec<Campaign>,
|
|
}
|
|
|
|
impl CampaignIndex {
|
|
pub fn load(worklane_dir: &Path) -> Result<Self> {
|
|
let dir = campaigns_dir(worklane_dir);
|
|
let mut campaigns = Vec::new();
|
|
|
|
// A board with no campaigns directory has no campaigns, which is not an error:
|
|
// every board made before campaigns existed is in that state.
|
|
if !dir.exists() {
|
|
return Ok(Self { campaigns });
|
|
}
|
|
|
|
for entry in fs::read_dir(&dir)?.filter_map(|e| e.ok()) {
|
|
let path = entry.path();
|
|
if !path.extension().is_some_and(|e| e == "md") {
|
|
continue;
|
|
}
|
|
let Ok(content) = fs::read_to_string(&path) else {
|
|
continue;
|
|
};
|
|
|
|
campaigns.push(Campaign {
|
|
uuid: parse_ticket_field(&content, "ID"),
|
|
title: heading_title(&content),
|
|
codename: parse_codename(&content),
|
|
content,
|
|
});
|
|
}
|
|
|
|
// By title, so a listing does not depend on the order the directory hands its
|
|
// entries back in.
|
|
campaigns.sort_by_key(|campaign| campaign.title.to_lowercase());
|
|
Ok(Self { campaigns })
|
|
}
|
|
|
|
/// The campaign carrying `uuid`, or nothing when the board no longer has it.
|
|
pub fn get(&self, uuid: &str) -> Option<&Campaign> {
|
|
self.campaigns.iter().find(|campaign| campaign.uuid == uuid)
|
|
}
|
|
|
|
pub fn iter(&self) -> impl Iterator<Item = &Campaign> {
|
|
self.campaigns.iter()
|
|
}
|
|
|
|
pub fn is_empty(&self) -> bool {
|
|
self.campaigns.is_empty()
|
|
}
|
|
}
|
|
|
|
/// The Campaign field as it reads, or empty for a ticket in no campaign.
|
|
///
|
|
/// A uuid no campaign carries renders as `_missing_`, the way a dangling relation
|
|
/// target does, rather than as the bare value the file stores: the value is a full
|
|
/// uuid, so showing it raw is thirty-six characters that say nothing about what is
|
|
/// gone.
|
|
pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> String {
|
|
let Some(uuid) = parse_campaign(content) else {
|
|
return String::new();
|
|
};
|
|
|
|
reference_cell(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()), colored)
|
|
}
|
|
|
|
/// The parts [`content_trim`] cannot render from the ticket file alone.
|
|
///
|
|
/// Both halves read the tree beside the ticket, so they are gathered in one place
|
|
/// rather than at each call site.
|
|
pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result<Resolved> {
|
|
Ok(Resolved {
|
|
relations: relations_for(content, worklane_dir)?,
|
|
campaign: campaign_cell(content, &CampaignIndex::load(worklane_dir)?, colored),
|
|
})
|
|
}
|
|
|
|
/// The members of a campaign, grouped by status in flow order.
|
|
///
|
|
/// Read through `collect_ticket_items`, the source `ls` and the board already use, so
|
|
/// there is no second parser and the rows print the way every other listing does.
|
|
/// Empty groups are kept: a campaign's shape is the four statuses, and a caller that
|
|
/// wants only the filled ones can say so.
|
|
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
|
|
let mut grouped = Vec::new();
|
|
|
|
// 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(),
|
|
};
|
|
|
|
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)
|
|
}
|
|
|
|
/// How far a campaign has got: members done against members held.
|
|
///
|
|
/// `Copy` because the board carries one on every `CampaignRow`, settled at reload: two
|
|
/// counters are cheaper to copy than to reach back through a reference for.
|
|
#[derive(Clone, Copy, Debug, Default)]
|
|
pub struct Standing {
|
|
pub done: usize,
|
|
pub total: usize,
|
|
}
|
|
|
|
impl Standing {
|
|
pub fn of(grouped: &[(&'static str, Vec<TicketItem>)]) -> Self {
|
|
Self {
|
|
done: grouped
|
|
.iter()
|
|
.filter(|(status, _)| *status == DONE)
|
|
.map(|(_, items)| items.len())
|
|
.sum(),
|
|
total: grouped.iter().map(|(_, items)| items.len()).sum(),
|
|
}
|
|
}
|
|
|
|
/// The count as it reads, or `no members` for a campaign nothing has been filed
|
|
/// against.
|
|
pub fn label(&self) -> String {
|
|
match self.total {
|
|
0 => "no members".to_string(),
|
|
total => format!("{}/{} done", self.done, total),
|
|
}
|
|
}
|
|
|
|
/// A campaign is done when it holds members and every one of them is done.
|
|
///
|
|
/// An empty campaign is neither, hence the `None`: calling it done would make a
|
|
/// container nothing has been filed against the most complete thing on the board,
|
|
/// and calling it open would claim work that does not exist.
|
|
pub fn state(&self) -> Option<&'static str> {
|
|
match (self.total, self.done == self.total) {
|
|
(0, _) => None,
|
|
(_, true) => Some(DONE),
|
|
(_, false) => Some("open"),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// The campaign file as it is written.
|
|
///
|
|
/// The codename sits directly under the ID, because that is what it is: a second way to
|
|
/// say which campaign this is, in a word rather than in thirty-six characters.
|
|
///
|
|
/// The same shape a ticket has, minus what a campaign has no use for: no acceptance
|
|
/// criteria, because its definition of done is derived from its members rather than
|
|
/// written down, no implementation plan, and no Status, because it sits in no status
|
|
/// directory. The headings and the placeholder come from the section table in
|
|
/// `util.rs`, so the two file formats cannot drift apart on the spelling of a heading.
|
|
pub fn campaign_body(
|
|
title: &str,
|
|
description: &[String],
|
|
codename: Option<&str>,
|
|
id: &uuid::Uuid,
|
|
owner: Option<&str>,
|
|
created_at: &str,
|
|
) -> String {
|
|
// Joined with a single newline, so an empty value is how a caller spells a
|
|
// paragraph break, exactly as it is for a ticket.
|
|
let description = trim_blank_ends(description);
|
|
let description_text = match description.is_empty() {
|
|
true => DESCRIPTION.placeholder.to_string(),
|
|
false => description.join("\n"),
|
|
};
|
|
|
|
format!(
|
|
"# {title}\n\
|
|
\n\
|
|
{description_heading}\n\
|
|
{description_text}\n\
|
|
\n\
|
|
{metadata_heading}\n\
|
|
\n\
|
|
- **ID**: {id}\n\
|
|
- **{codename_field}**: {codename}\n\
|
|
- **Owner**: {owner}\n\
|
|
- **Created At**: {created_at}\n\
|
|
",
|
|
description_heading = DESCRIPTION.heading,
|
|
metadata_heading = METADATA_HEADING,
|
|
codename_field = CODENAME_FIELD,
|
|
// Written unset rather than left out, the way `add` writes an unset Due on every
|
|
// ticket: the line is then there to read and there to edit by hand, and one shape
|
|
// of file is one thing for the parser to be right about.
|
|
codename = codename.unwrap_or(NOT_SET),
|
|
owner = owner.unwrap_or(NOT_SET),
|
|
)
|
|
}
|