There was no way to group the tickets that have to be finished together. A goal such as a v1 release was either one ticket that could not describe its parts, or a set of tickets with the goal restated in every description and nothing tying them together. A campaign is a file of its own under `.worklane/campaigns/`, with a title, a description and metadata, and it sits in no status directory. 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 beside `mv`'s. An empty campaign is neither open nor done, since calling it done would make a container nothing has been filed against the most complete thing on the board. Membership is one field on the *member*, Campaign in the ticket Metadata, written only by `assign`. The member list is deliberately not on the campaign: that would put membership in two places and make one file that every assignment edits, contended the moment two agents share a board. So `add` gains no `--campaign` and neither does `set`. `add` does not write the field either. Every ticket written before campaigns existed has none, so the insertion path has to exist regardless, and leaving it out of `add` means one path that is always exercised rather than two. That is the Relations argument from 4179958, applied to a field instead of a section. `set_or_insert_metadata_field` is the upsert and `METADATA_ORDER` is its anchor list, the way `SECTION_ORDER` is `ensure_section`'s, so Campaign lands beside Status rather than at the end and Status stays last. A file with no Metadata heading is an error rather than an insertion, per 641e3d5. The three tiers came out of `resolve_ticket` into `resolve_in`, shared by both kinds. A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step. Two things fell out of that. `Found.dir` is the status for a ticket and empty for a campaign, which is what drops the bracket from the ambiguity listing for one. And `resolve_ticket` can now explain a search that names a campaign, so `mv`, `show`, `chown` and everything else that takes a ticket give the same reason instead of a bare "no ticket found" — one place rather than a check per command. Only on the zero-match path, so an ambiguous ticket error is never replaced by a complaint about a directory the caller never mentioned. The stored value is the full uuid, per the same rule the Relations section follows, and the title is resolved for display. `reference_cell` is now shared between the two, so a dangling campaign and a dangling relation target are both `_missing_` rather than each inventing a spelling. `Resolved` carries what `content_trim` cannot render from the file alone: a struct rather than two more parameters, so the next such field is one entry instead of an edit at every call site. `campaign show` lists done members, unlike `ls`, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks. `ls --campaign` is the other way round and keeps every rule `ls` already has. Deliberately out of scope. The derived progress figure is 1cb999f, now recorded as blocked by this, since nothing here can compute it yet. Unassigning needs a field cleared back to unset, which is 74904dc. And the board gets neither a campaign tab nor a card marker: the detail view resolves the field because it renders the body, and that is all. A marker would want a read per reload and the four corners are already spent, which is the b8ce18c reasoning; filed as 61879a4. Twenty-four integration tests and eleven unit tests, covering assign, reassign, the no-op, a dangling campaign, the ls filter, `mv` refusing a campaign, insertion placement, and a handwritten section and unknown metadata field surviving an assignment verbatim. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
295 lines
10 KiB
Rust
295 lines
10 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,
|
|
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 {
|
|
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.
|
|
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),
|
|
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_block(content, worklane_dir, colored)?,
|
|
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 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],
|
|
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\
|
|
- **Owner**: {owner}\n\
|
|
- **Created At**: {created_at}\n\
|
|
",
|
|
description_heading = DESCRIPTION.heading,
|
|
metadata_heading = METADATA_HEADING,
|
|
owner = owner.unwrap_or("_Not set_"),
|
|
)
|
|
}
|