Files
worklane/src/campaign.rs
T
Ansho ReiandClaude Opus 5 528566d103 (61879a4) Surface campaigns on the board, and bump to 0.20.0
A card label and a frame, not a campaign tab. A tab had to say what its
columns are, and a campaign groups across the flow rather than within one
status, so the answer is the four columns filtered: a filter on the board
it already has, not a fifth tab.

So a card names its campaign on the label row, before the tags, marked ~
and bold, and the row drops the tags whole before it drops the campaign.
`c` opens a picker; taking a campaign filters every column to its members
and draws a frame above them carrying the id, the codename, the name, the
opening line of the description and the standing. The standing comes from
the columns, since while a campaign is selected the columns are its
members. `q` takes off one layer at a time: the overlay, the filter, the
board.

The label needs something to say, which the stored uuid is not, so
campaigns gained `Codename`: one word, `v1` or `beaver`, written by
`campaign add --codename` and validated at parse time. `campaign ls`
prints it and `resolve_in` gained an exact-codename tier above the uuid
prefix, or it would be a field you can read and cannot type. Only
campaigns carry the field, so the tier is empty for a ticket and ticket
resolution is unchanged.

The campaigns index is read once per project in `columns_of`, on the pass
that already builds the cards, and `digest` now watches the campaigns
directory: without it a campaign filed elsewhere never reached the picker.
`frame_rows` grew a row, so the two bools deciding the geometry became one
`Chrome` and the row indices are named.

Left out and filed as d637288: nothing can give a codename to a campaign
that is already on the board.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:09:07 +02:00

313 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();
for status in status_dirs() {
let status_path = worklane_dir.join(status);
let items = match status_path.exists() {
true => collect_ticket_items(&status_path)?,
false => Vec::new(),
};
grouped.push((
status,
items
.into_iter()
.filter(|item| item.campaign.as_deref() == Some(uuid))
.collect(),
));
}
Ok(grouped)
}
/// How far a campaign has got: members done against members held.
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),
)
}