//! 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 { 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, 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 { 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 { 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, } impl CampaignIndex { pub fn load(worklane_dir: &Path) -> Result { 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 { 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 { 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)>> { 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 = 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)]) -> 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), ) }