campaign ls printed every campaign and offered no way to narrow it, and the row was assembled by hand, so a long title pushed the standing out of line with the row above it and the created date the file already carries was not shown at all. --state takes open, done or empty and matches against Standing::state(), so the derived value keeps one definition: a campaign reads [open] in the listing if and only if --state open lists it. --state rather than --status, which names one of the five ticket statuses everywhere else and would invite --state backlog here. empty is the third value because an empty campaign derives None deliberately, and a filter that could not reach those would leave what has been filed and forgotten answerable only by reading the whole listing. A filter that matches nothing names the value back, since a silent listing reads as the other empty case. The filter reaches --ids as well, the way ls --ids keeps its own, and is the only thing that makes that path count members: an unfiltered completion is as cheap as it was. The columns are measured on the raw values and padded before anything is painted, the rule metadata_cells follows. The codename is measured with the title rather than given a column of its own: a campaign filed without one spends nothing on it, so a column for it would be one most rows pad into and some leave empty, and what a reader lines up is where a name ends and its progress begins. A flag's possible values now come off the command that holds the flag, so campaign ls --state reaches ls's own arguments rather than campaign's. The prompt offered nothing there while fish offered the three values, which made a liar of the rule that a ValueEnum added anywhere is typeable on the board the day it is added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
393 lines
15 KiB
Rust
393 lines
15 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,
|
|
}
|
|
|
|
impl Campaign {
|
|
/// The name a reader knows the campaign by: the codename, or the title for a
|
|
/// campaign filed without one.
|
|
///
|
|
/// What the history log records for a campaign move. The field holds a uuid, which
|
|
/// says nothing in a log line, and resolving at read time would let an entry change
|
|
/// meaning when a campaign is renamed, so the name is settled when the entry is
|
|
/// written. The codename over the title because it is the word the board and the
|
|
/// command line already use for the campaign, and a log row holds two of these
|
|
/// around an arrow.
|
|
pub fn name(&self) -> &str {
|
|
self.codename.as_deref().unwrap_or(&self.title)
|
|
}
|
|
}
|
|
|
|
/// 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_cells(content: &str, index: &CampaignIndex) -> Vec<Cell> {
|
|
let Some(uuid) = parse_campaign(content) else {
|
|
return Vec::new();
|
|
};
|
|
|
|
reference_cells(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()))
|
|
}
|
|
|
|
/// 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) -> Result<Resolved> {
|
|
Ok(Resolved {
|
|
relations: relations_for(content, worklane_dir)?,
|
|
campaign: campaign_cells(content, &CampaignIndex::load(worklane_dir)?),
|
|
})
|
|
}
|
|
|
|
/// The members of a campaign, grouped by status in flow order, discarded last.
|
|
///
|
|
/// 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 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)
|
|
}
|
|
|
|
/// A campaign with work outstanding, beside [`DONE`] for one with none left.
|
|
///
|
|
/// Not a [`Status`]: no ticket is ever in it and no directory is named for it. It is the
|
|
/// campaign's own two-word vocabulary, and it is a const because the listing prints it,
|
|
/// [`Standing::state`] derives it and [`CampaignState`] filters on it.
|
|
pub const OPEN: &str = "open";
|
|
|
|
/// 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 {
|
|
// Discarded counts as finished: the work was decided out of the campaign,
|
|
// not left in it, and one abandoned ticket must not hold a campaign open
|
|
// forever. The same predicate `mv` gates on, so "nothing outstanding" means
|
|
// one thing across the tool.
|
|
done: grouped
|
|
.iter()
|
|
.filter(|(status, _)| !is_open(status))
|
|
.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 state a campaign is in, as `campaign ls --state` accepts it.
|
|
///
|
|
/// A `ValueEnum` for the reason [`Status`] is one: an unknown value is clap's to refuse
|
|
/// at parse time with the three listed, no handler has to check, and every shell that
|
|
/// completes possible values gets them for free.
|
|
///
|
|
/// `--state` and not `--status`, which names one of the five ticket statuses everywhere
|
|
/// else in the tool. A campaign sits in no status directory, and borrowing the word for
|
|
/// a different vocabulary is how a reader comes to type `--status backlog` here.
|
|
///
|
|
/// `Empty` is the third value because [`Standing::state`] answers `None` for a campaign
|
|
/// nothing has been filed against, deliberately, and a filter that could not reach those
|
|
/// would leave the one question a grooming sweep asks — what has been filed and forgotten
|
|
/// — answerable only by reading the whole listing.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
|
|
pub enum CampaignState {
|
|
/// Holds members, and at least one of them is not finished
|
|
Open,
|
|
/// Holds members, and every one of them is done or discarded
|
|
Done,
|
|
/// Holds no members at all, so it is neither open nor done
|
|
Empty,
|
|
}
|
|
|
|
impl CampaignState {
|
|
/// The value as it is typed, which is what a message naming the filter repeats back.
|
|
pub fn as_str(self) -> &'static str {
|
|
match self {
|
|
Self::Open => OPEN,
|
|
Self::Done => DONE,
|
|
Self::Empty => "empty",
|
|
}
|
|
}
|
|
|
|
/// Whether a campaign in this standing is the one the filter asked for.
|
|
///
|
|
/// Matched against [`Standing::state`] rather than against the counters, so the
|
|
/// derived value has one definition: a campaign reads `[open]` in the listing if and
|
|
/// only if `--state open` lists it.
|
|
pub fn holds(self, standing: &Standing) -> bool {
|
|
match self {
|
|
Self::Empty => standing.state().is_none(),
|
|
wanted => standing.state() == Some(wanted.as_str()),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// 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),
|
|
)
|
|
}
|