Files
worklane/src/campaign.rs
T
Ansho ReiandClaude Opus 5 634a1f44c4 (07ac4e1) Filter campaign ls by state, and lay its listing out as a table, and bump to 0.33.6
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>
2026-09-15 16:42:21 +02:00

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),
)
}