Files
worklane/src/command.rs
T

1112 lines
45 KiB
Rust

use clap::Parser;
use std::sync::LazyLock;
use chrono::NaiveDate;
use crate::util::{Clearable, PRIORITY_RANGE, RelationKind, Status, priority_legend};
/// clap wants a `&str` with a long enough lifetime, and the legend is built from
/// the same ramp the listing uses rather than spelled out a second time.
static PRIORITY_LEGEND: LazyLock<String> = LazyLock::new(priority_legend);
/// Reject a level outside the range at parse time, so no command has to.
fn priority_level(raw: &str) -> Result<u8, String> {
match raw.parse::<u8>() {
Ok(level) if PRIORITY_RANGE.contains(&level) => Ok(level),
_ => Err(format!(
"priority must be a whole number from {} to {}",
PRIORITY_RANGE.start(),
PRIORITY_RANGE.end()
)),
}
}
/// What `--version` prints: the crate version and the commit it was built from.
///
/// The sha is the part that matters. Two binaries built weeks apart both call
/// themselves 0.1.0, so without it there is no way to tell whether the copy on
/// PATH is the one carrying a given fix.
const VERSION: &str = concat!(env!("CARGO_PKG_VERSION"), " (", env!("WORKLANE_GIT_SHA"), ")");
#[derive(Parser)]
#[command(name = "worklane")]
#[command(about = "A CLI tool for managing project status")]
#[command(version = VERSION)]
#[command(propagate_version = true)]
pub struct Cli {
/// Absent opens the board view, the way a bare `frig` does.
#[command(subcommand)]
pub command: Option<Command>,
}
/// Reject an empty value at parse time, so it lands as a usage error rather than a
/// runtime one.
///
/// Two messages rather than one, because the arguments that use this fall into two
/// kinds. A search term or a title has no empty form at all, and that is all this says.
/// A field that *can* be emptied says so and names `--clear`, which is [`clearable`]
/// below: an accidentally empty variable must not blank a field silently, and somebody
/// typing an empty value on purpose is reaching for exactly the flag that does it.
///
/// Only the scalars use either one. For the multi-line sections an empty value is a
/// paragraph break.
fn non_empty(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty".to_string());
}
Ok(raw.to_string())
}
/// Reject an empty value on an argument whose field can be cleared, and say how.
///
/// The message names no command, because the arguments that use this belong to three:
/// `set --tags`, `set --due`, `add --due` and the `chown` user. `set` and `chown` both
/// take a `--clear`; `add` does not, and there a field is left unset by omitting the
/// flag, which is what the caller was reaching for anyway.
fn clearable(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty, use --clear to return a field to unset".to_string());
}
Ok(raw.to_string())
}
/// Reject a due date that is not a real calendar date in the promised form.
///
/// At parse time, like `priority_level`, so a mistyped date is a usage error with
/// nothing written rather than a value the board goes on showing. `--due` is one of the
/// scalars deliberately left without `PROSE`, so this is the same bargain: nothing here
/// holds prose, and a wrong value should stop the command.
///
/// **The shape is checked before chrono sees it.** `%Y-%m-%d` accepts an unpadded
/// `2026-8-9`, which would then be stored exactly as typed and sort before `2026-10-01`
/// in any comparison of the strings. Checking the length and the two dashes first is
/// what lets a valid date be stored unchanged rather than normalised on the way in.
///
/// Strict on the way in, tolerant on the way out: `util::due_date` still cuts a
/// datetime down to its date, because a file written before this existed, or by hand,
/// can hold one and still has to render.
fn iso_date(raw: &str) -> Result<String, String> {
// An empty value keeps the message that explains why it is refused, since somebody
// typing it is reaching for a way to clear the field rather than mistyping a date.
clearable(raw)?;
let bytes = raw.as_bytes();
let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-';
if !shaped || NaiveDate::parse_from_str(raw, "%Y-%m-%d").is_err() {
// Not echoing the value: clap has already printed `invalid value '...' for
// '--due <DUE>'` above this line, and `priority_level` says its piece the same
// way.
return Err(
"due date must be a real calendar date written as YYYY-MM-DD, for example 2026-08-29"
.to_string(),
);
}
Ok(raw.to_string())
}
/// Reject a codename that is not one word.
///
/// At parse time, like `iso_date` and `priority_level`, so a mistyped value is a usage
/// error with nothing written. One word because the board draws it as a label beside the
/// tags, with a mark and no quoting: `~beaver release` on that row reads as two labels, and
/// the second one is not a campaign. A title is where a sentence goes.
///
/// Nothing else is checked. There is no registry of codenames to check against, the same
/// reason `ls --tag` refuses to validate a tag, and a length limit would be a number
/// invented here: a label the column will not hold is dropped whole by the row that draws
/// it.
fn codename(raw: &str) -> Result<String, String> {
let value = non_empty(raw)?;
if value.split_whitespace().count() > 1 {
return Err("codename must be a single word, for example v1 or beaver".to_string());
}
Ok(value)
}
/// Reject a tag value that `ls --tag` could never match.
///
/// `--tag` matches a whole value of the comma-separated Tags field, so a value carrying a
/// comma is two tags and would be declared under a name nothing can be filtered by. A line
/// break is refused for the file's sake rather than the filter's: a tag is a heading in
/// `tags.md`, and a heading is one line.
///
/// Trimmed rather than refused for surrounding space, because `parse_tags` trims every
/// value it reads off a ticket and [`TagIndex::parse`] trims every heading it reads off the
/// vocabulary. Refusing here would refuse a value that both of those accept.
///
/// [`TagIndex::parse`]: crate::tag::TagIndex::parse
fn tag_value(raw: &str) -> Result<String, String> {
let value = raw.trim();
if value.is_empty() {
return Err("tag cannot be empty".to_string());
}
if value.contains(',') {
return Err(
"tag cannot contain a comma, which is what separates one tag from the next".to_string()
);
}
if value.contains(['\n', '\r']) {
return Err("tag must be a single line".to_string());
}
Ok(value.to_string())
}
/// Reject an annotation the vocabulary file or the listing cannot carry.
///
/// The vocabulary is one heading per tag with its prose under it, so a line of prose
/// starting with the section marker would split the annotation and declare whatever
/// followed. A tab anywhere in the value is refused for the listing's sake rather than the
/// file's: `tags ls` prints one tag, its count and the annotation's opening line as three
/// tab-separated fields, so an annotation holding a tab reads as the start of a fourth
/// field and everything after it is silently gone.
///
/// Both are refused at parse time, where nothing has been written, rather than escaped on
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking
/// for a different line.
fn annotation_line(raw: &str) -> Result<String, String> {
if raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
return Err(format!(
"an annotation line cannot start with '{}', which is how the vocabulary file \
starts a tag",
crate::tag::SECTION
));
}
if raw.contains('\t') {
return Err(
"an annotation cannot contain a tab, which is how `tags ls` separates its fields"
.to_string(),
);
}
Ok(raw.to_string())
}
/// What `--actor` says on every command that writes a history entry.
///
/// One string, so the five spell it the same: a flag documented differently on each
/// command reads as five flags.
const ACTOR_HELP: &str = "Who the entry is attributed to, overriding WORKLANE_ACTOR and the git user. Free text, checked against nothing";
/// What `--actor-from-git` says on every command that writes a history entry.
///
/// The counterpart to [`ACTOR_HELP`]: where that one names somebody specific, this one
/// says attribute it to the human whose checkout this is, without knowing how they spell
/// themselves.
const ACTOR_FROM_GIT_HELP: &str = "Attribute the entry to the detected git user instead of WORKLANE_ACTOR, for acting on the person's behalf. Cannot be combined with --actor";
/// Arguments that carry prose, and therefore have to accept a value starting with
/// a hyphen.
///
/// Ticket text quotes flag names constantly, and without this a criterion reading
/// "--print is supported" is parsed as a flag and the whole ticket is refused. The
/// trade, spelled out in docs/cli-arguments.md: on these arguments a genuinely mistyped flag
/// now lands as content instead of raising a usage error. That is the right way
/// round for prose, and it is why `due`, `priority`, `tags`, `owner` and `status`
/// are deliberately left without it.
const PROSE: bool = true;
#[derive(clap::Subcommand)]
pub enum Command {
/// Initialize worklane in the current project
Init {
/// Create a board even where a committed pointer names one that is not here
#[arg(long)]
create: bool,
},
/// Add a new ticket to the backlog
Add(AddArgs),
/// List tickets, optionally filtered by status
#[command(after_help = PRIORITY_LEGEND.as_str())]
Ls(LsArgs),
/// Show a ticket by UUID or title
Show {
/// Ticket UUID or title to search for
id: String,
},
/// Move a ticket to a different status
Mv(MvArgs),
/// Replace fields on an existing ticket
Set(SetArgs),
/// Add to a section of an existing ticket
Append(AppendArgs),
/// Record a relation from one ticket to another
Relate(RelateArgs),
/// Change the owner of a ticket, or return it to unset
///
/// User first, ticket second, after Unix `chown`. That reverses the ticket-first
/// order `mv`, `comment` and `show` use, deliberately: the name borrows the Unix
/// association, so the argument order borrows it too.
///
/// A swap is caught by resolution rather than by a check of its own. Given
/// `chown 641e3d5 alice` the second argument has to resolve as a ticket, and a bare
/// username usually will not, so the call fails on its own. It is silently wrong
/// only when both arguments resolve, which needs a ticket whose title matches the
/// username.
Chown(ChownArgs),
/// Open the board view
Tui {
/// Projects to monitor, each resolved to the first `.worklane` at or above it.
/// Several are shown as tabs. Defaults to the working directory
paths: Vec<std::path::PathBuf>,
},
/// Tick acceptance criteria
Check(CheckArgs),
/// Untick acceptance criteria
Uncheck(CheckArgs),
/// Add a comment to a ticket
Comment {
/// Ticket UUID or title
ticket: String,
/// Comment body (required)
#[arg(allow_hyphen_values = PROSE)]
body: String,
/// Named after the writer of the entry, not after the ticket's assignee, which
/// is `chown`'s. It was `--owner`, which said the wrong one of the two.
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
actor_from_git: bool,
},
/// Group tickets that have to be finished together
Campaign {
#[command(subcommand)]
command: CampaignCommand,
},
/// Put a ticket in a campaign
///
/// Campaign first, ticket second, after `chown` and for the same reason: the
/// container is what the call is about, and the order is worth being consistent
/// about across the two commands that name two things.
///
/// The only writer of the Campaign field. `add` has no `--campaign` and `set` has
/// no `--campaign`, so the field keeps one writer the way Owner and Status do.
Assign {
/// Campaign UUID or title
campaign: String,
/// Ticket UUID or title
ticket: String,
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
actor_from_git: bool,
},
/// The tag vocabulary: what the board carries, and what each tag means
///
/// A command rather than a mode on `ls`, for two reasons. `ls --tag <tag>` answers
/// "what is tagged bug" and cannot answer "what tags exist", which is the question a
/// grooming sweep starts from; and a `--tags` beside a `--tag` is one letter away from
/// a filter that means something else.
///
/// The listing is machine-readable, like `ls --ids`: the tag, a tab, the count.
Tags {
#[command(subcommand)]
command: Option<TagCommand>,
},
/// Print a shell completion script
///
/// The structure comes from the clap definition, so a flag added here appears
/// without anyone remembering to. Fish gets a hand-written half appended for the
/// values only the board knows, see `completions.rs`.
Completions {
/// fish, bash, zsh, elvish or powershell
shell: clap_complete::Shell,
},
/// Install the agent skills that teach an agent to use worklane
///
/// Every shipped document by default. The optional name narrows it to one, and
/// `--print` requires it: a diff is against one document, and printing them all
/// concatenated would only look like one.
InstallSkill {
/// Skill to install or print, all of them if omitted
skill: Option<String>,
/// Overwrite an existing copy that has been modified
#[arg(long)]
force: bool,
/// Write it to stdout instead of installing it
#[arg(long)]
print: bool,
},
/// Install the opencode tool definitions that wrap the worklane CLI
///
/// One artifact, so no name to pass where `install-skill` takes an optional one:
/// `--print` here can only mean the one file. opencode alone, and globally, so the
/// tools are there in every project rather than in a checkout that happens to carry
/// them. Claude Code has no directory it scans for a tool definition; reaching it
/// would mean an MCP server, which is not this file.
InstallTool {
/// Overwrite an existing copy that has been modified
#[arg(long)]
force: bool,
/// Write it to stdout instead of installing it
#[arg(long)]
print: bool,
},
}
/// What a campaign can be asked for.
///
/// No `mv`: a campaign has no status to move it to, its state is derived from its
/// members.
///
/// `set` and `append` arrive together, 32e98ab, because for a prose section they are a
/// pair: a way to replace a description with no way to add a paragraph to one is the half
/// that is easy to reach for and wrong, since replacing a description to add a sentence is
/// how the rest of it gets lost. The two scalars have no append form at all, which is the
/// same line `append` already draws for a ticket.
///
/// **`append` is a campaign's own subcommand and not the top-level `append`.** That one
/// resolves a ticket, and its positional would then name either object: `resolve_in`'s tiers
/// are the same over both directories, so a search can resolve in each and nothing but a
/// flag could say which was meant. It would also make a liar of `resolve_ticket`, which
/// explains a ticket search that names a campaign. Under `campaign` the object is settled by
/// the command, the way it is for `set`, `show` and `ls`.
#[derive(clap::Subcommand)]
pub enum CampaignCommand {
/// File a new campaign
Add(CampaignAddArgs),
/// Replace fields on an existing campaign
///
/// The only way to change a campaign's title or codename after it is filed.
/// `campaign add --codename` writes the field at creation the way `add --title` does for
/// a ticket; this is what replaces it, so every campaign filed before the field existed
/// can still be given one.
Set(CampaignSetArgs),
/// Add a paragraph to a campaign's description
///
/// The other half of `campaign set --description`, and the half that keeps what is
/// already written: a description is the sentence a whole campaign's members are filed
/// against, so adding a line to it must not mean retyping it.
Append(CampaignAppendArgs),
/// List campaigns with their member counts
Ls {
/// Print one campaign per line as its id and title, tab separated, for a script
/// or a completion
///
/// The same flag and the same two fields as `ls --ids`, since it answers the same
/// question about a different object. Member counts are left out: counting them
/// reads every ticket on the board, and the caller here is a shell filling in a
/// candidate list on a keypress
#[arg(long)]
ids: bool,
},
/// Show a campaign and its members grouped by status
Show {
/// Campaign UUID or title
campaign: String,
},
}
/// What can be replaced on a campaign that is already filed: everything it holds but its
/// owner.
///
/// No `--owner`: nothing writes a campaign's Owner today, and giving `set` one would settle
/// by accident whether `chown` grows a campaign or `set` keeps the field, which is the
/// one-field-one-writer question and not this command's to answer.
///
/// No `--clear`, which is 32e98ab's decision and not a deferral. A codename is replaced
/// rather than emptied, and a campaign's one prose section has no cleared form worth
/// reaching: emptying the description of a container six tickets are filed against is not a
/// thing anybody has asked for, and the only ways to spell it would be to put [`Clearable`]
/// on a campaign, whose variants are a ticket's fields, or to invent a second enum with one
/// variant in it. So an empty `--description ""` stays a paragraph break here exactly as it
/// is everywhere else, and the refusal for an all-blank value says there is nowhere to go
/// back to rather than naming a flag that does not exist.
///
/// `--force` guards the codename and nothing else. A campaign that already has one is
/// referred to by it: it is on every card in the campaign, it is what resolves it at the
/// command line, and it is very likely in somebody's shell history. Replacing that silently
/// is the same mistake overwriting an edited skill document would be, which is what
/// `install-skill --force` exists for. A title needs no guard, since a campaign always has
/// one and replacing it is the whole point of the flag. Neither does a description: it is
/// prose written to be revised, the same reason `tags set --annotation` has no guard, and a
/// guard in front of the command's whole purpose is worse than no command.
///
/// The group makes at least one field mandatory, so a bare `worklane campaign set <c>` is a
/// usage error rather than a silent no-op, exactly as it is for [`SetArgs`].
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("campaign_set_fields")
.required(true)
.multiple(true)
.args(["title", "description", "codename"])
))]
pub struct CampaignSetArgs {
/// Campaign UUID, title, filename or codename
pub campaign: String,
/// Replace the campaign title, renaming the file to match
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
pub title: Option<String>,
/// Replace the description. Repeat the flag for more lines, empty for a paragraph break
///
/// The whole section, so a paragraph added to it is `campaign append --description`
/// rather than the description retyped
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// Replace the codename, a single word to call the campaign by
///
/// The same parser `campaign add --codename` takes, so a codename is one thing however
/// it was written. Replacing one a campaign already has needs `--force`
#[arg(short, long, value_parser = codename)]
pub codename: Option<String>,
/// Replace a codename the campaign already has
///
/// Without it, `--codename` on a campaign that already has one is refused and nothing
/// is written. The codename is how a campaign is referred to once it has one, on every
/// card in it and at the command line, so changing it is a decision rather than a
/// correction. Setting the codename a campaign already carries is a no-op either way,
/// not a refusal: there is nothing to overwrite
#[arg(short, long)]
pub force: bool,
}
/// What can be added to a campaign that is already filed: a paragraph of its description.
///
/// One field, so it is `required` rather than a group of one, which is the longer way to say
/// the same thing and the shape [`TagSetArgs`] already takes. A bare
/// `worklane campaign append <c>` is therefore a usage error rather than a silent no-op.
///
/// No `--title` and no `--codename`, because appending to a scalar has no meaning. That is
/// the line `append` already draws for a ticket, where the title is absent for the same
/// reason.
#[derive(clap::Args)]
pub struct CampaignAppendArgs {
/// Campaign UUID, title, filename or codename
pub campaign: String,
/// Add a paragraph to the description. Repeat the flag for more lines within it
#[arg(short, long, required = true, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
}
/// What a campaign holds: a title, a description and an owner.
///
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
/// campaign's definition of done is derived from its members rather than written down,
/// and no implementation plan. Priority, tags and a due date are left out because
/// nothing reads them yet, and a field written but never shown is a field that goes
/// stale unnoticed.
///
/// `--codename` is the exception to that last rule and earns it: the board draws it on
/// every card in the campaign, and it exists because the uuid does not fit there.
#[derive(clap::Args)]
pub struct CampaignAddArgs {
/// Campaign title
#[arg(short, long, allow_hyphen_values = PROSE)]
pub title: String,
/// What the campaign is for. Use multiple flags for multiline descriptions
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// A single word to call the campaign by, for example v1 or beaver
///
/// The uuid is what every command stores and the title is a sentence, so neither is
/// what a card has room to print. This is the short form the board draws, and it is
/// optional: a campaign without one is drawn by its short id instead.
#[arg(short, long, value_parser = codename)]
pub codename: Option<String>,
/// Owner. Defaults to the git user
#[arg(short, long)]
pub owner: Option<String>,
}
/// What the tag vocabulary can be asked for.
///
/// Optional, unlike [`CampaignCommand`], and that is the whole shape of the compatibility
/// here: `worklane tags` was the listing before it was a group, the shipped fish completion
/// calls it that way to fill in `ls --tag`, and a bare call turning into a usage error would
/// break a script for the sake of symmetry. So the bare form stays the listing, and `tags
/// ls` is the same thing spelled the way `campaign ls` is.
///
#[derive(clap::Subcommand)]
pub enum TagCommand {
/// Declare a tag, and what it means
Add(TagAddArgs),
/// Replace what a declared tag means
Set(TagSetArgs),
/// List the tags the board carries, and how many tickets carry each
Ls,
}
/// What declaring a tag takes: the tag, and what it is for.
///
/// No owner and no timestamp, which every other file under `.worklane/` carries. A tag is
/// not an object with a history, it is a word the board agrees on, and `git log` over
/// `tags.md` answers who wrote which line better than a field would.
#[derive(clap::Args)]
pub struct TagAddArgs {
/// The tag to declare, spelled the way `ls --tag` matches it
#[arg(value_parser = tag_value)]
pub tag: String,
/// What the tag means and when it is appropriate. Use multiple flags for multiline
/// annotations
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = annotation_line)]
pub annotation: Vec<String>,
}
/// What can be replaced on a tag that is already declared: what it means, and nothing else.
///
/// No `--force`, unlike [`CampaignSetArgs`]. A codename is guarded because once a campaign
/// has one it is how the campaign is addressed, on every card and at every command line, so
/// replacing it silently breaks the way it is referred to. An annotation is prose written to
/// be revised and nothing addresses anything by it, so a guard would stand in front of the
/// command's whole purpose.
///
/// No rename. The tag *is* the key, so changing it means rewriting the Tags field of every
/// ticket carrying it. That is a migration, not a flag on `set`.
///
/// No `--clear`. An annotation is emptied with `--annotation ""`, which writes the same
/// placeholder a tag declared without one gets, so a second spelling would add nothing.
/// [`Clearable`] is a ticket's fields anyway, per [`SetArgs`].
///
/// `--annotation` is required, so a bare `worklane tags set <tag>` is a usage error rather
/// than a silent no-op, exactly as the group on [`CampaignSetArgs`] makes it for a campaign.
#[derive(clap::Args)]
pub struct TagSetArgs {
/// The tag to change, spelled the way it is declared
#[arg(value_parser = tag_value)]
pub tag: String,
/// What the tag means and when it is appropriate, replacing whatever it said before. Use
/// multiple flags for multiline annotations
#[arg(
short,
long,
required = true,
allow_hyphen_values = PROSE,
value_parser = annotation_line
)]
pub annotation: Vec<String>,
}
/// `ls` holds four filters, an output mode and nothing else, which is the boundary the
/// Rust Style rule in docs/rust-style.md names: two of the filters are adjacent `Option<String>`
/// values that a caller can swap silently, so the mode that joined them came as a
/// struct rather than a sixth parameter, the way `add` became [`AddArgs`].
#[derive(clap::Args)]
pub struct LsArgs {
/// Filter by status
pub status: Option<Status>,
/// Only show tickets at this priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
pub priority: Option<u8>,
/// Only show tickets carrying this tag, matched whole
#[arg(long, value_parser = non_empty)]
pub tag: Option<String>,
/// Only show the members of this campaign, by UUID or title
#[arg(long, value_parser = non_empty)]
pub campaign: Option<String>,
/// Print one ticket per line as its id and title, tab separated, for a script or a
/// completion. Done included, and the filters still apply
#[arg(long)]
pub ids: bool,
}
/// `add` carries every field a new ticket can hold, so it is a struct rather than an
/// inline variant: nine parameters at the call site is what `too_many_arguments` is
/// for, and `set`, `append` and `check` already pass their arguments this way.
///
/// No `ArgGroup`: `--title` is required on its own, and everything else is optional
/// because a ticket with only a title is a valid thing to file.
#[derive(clap::Args)]
pub struct AddArgs {
/// Ticket title
#[arg(short, long, allow_hyphen_values = PROSE)]
pub title: String,
/// Ticket description. Use multiple flags to create multiline descriptions.
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// Acceptance criteria. Accepts multiple flags, each will be interpreted as a single criterium
#[arg(short, long, allow_hyphen_values = PROSE)]
pub acceptance: Vec<String>,
/// Implementation plan. Accepts multiple flags, each will be interpreted as a single step
#[arg(short, long, allow_hyphen_values = PROSE)]
pub plan: Vec<String>,
/// Tags (comma-separated)
#[arg(short = 'g', long)]
pub tags: Vec<String>,
/// Due date (YYYY-MM-DD)
#[arg(long, value_parser = iso_date)]
pub due: Option<String>,
/// Owner
#[arg(short, long)]
pub owner: Option<String>,
/// Priority, 1 (most urgent) to 5 (least). Left unset if omitted.
#[arg(long, value_parser = priority_level)]
pub priority: Option<u8>,
}
/// `mv` grew past a handful of parameters when `--actor-from-git` arrived, so it is a
/// struct like `set` and `append` rather than an inline variant.
#[derive(clap::Args)]
pub struct MvArgs {
/// Ticket UUID or title
pub ticket: String,
/// Target status
#[arg(short, long)]
pub status: Status,
/// Force move (allows backward or non-sequential moves)
#[arg(short, long)]
pub force: bool,
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
/// Why the ticket moved, recorded in the history entry beside the transition
/// it explains. Prose, so it takes a leading hyphen
#[arg(long, allow_hyphen_values = PROSE)]
pub reason: Option<String>,
}
/// `set` replaces a field outright. Owner is deliberately absent: `chown` owns that
/// field, and status is `mv`'s, so no field has two writers.
///
/// The group makes at least one field mandatory, so a bare `worklane set <ticket>` is
/// a usage error rather than a silent no-op.
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("set_fields")
.required(true)
.multiple(true)
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority", "clear"])
))]
pub struct SetArgs {
/// Ticket UUID or title
pub ticket: String,
/// Replace the ticket title, renaming the file to match
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
pub title: Option<String>,
/// Replace the description. Repeat the flag for more lines, empty for a paragraph break
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// Replace the acceptance criteria. Repeat the flag, one criterium per value
#[arg(short, long, allow_hyphen_values = PROSE)]
pub acceptance: Vec<String>,
/// Replace the implementation plan. Repeat the flag, one step per value
#[arg(short, long, allow_hyphen_values = PROSE)]
pub plan: Vec<String>,
/// Replace the tags
#[arg(short = 'g', long, value_parser = clearable)]
pub tags: Vec<String>,
/// Replace the due date (YYYY-MM-DD)
///
/// The same parser as `add`: one field, one definition of what a due date is. The
/// planning skill sets dates through `set` rather than `add`, so validating only
/// the one that files a ticket would leave the path that is actually used open.
#[arg(long, value_parser = iso_date)]
pub due: Option<String>,
/// Replace the priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
pub priority: Option<u8>,
/// Return a field to unset. Repeat the flag for more than one
///
/// The counterpart to the flag it names, and the only way to take a value away: an
/// empty value is a paragraph break for a section and a usage error for a scalar, so
/// neither can spell this. What goes back is what `add` writes for a field it was
/// never given.
///
/// No `title`, which addresses the ticket and names its file, and no `owner`, which
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
#[arg(long, value_name = "FIELD")]
pub clear: Vec<Clearable>,
/// Only reaches the entry `--tags` writes, since that is the one field of this
/// command's that is logged
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
}
impl SetArgs {
/// A field this call both replaces and clears, if there is one.
///
/// clap cannot express the conflict, because `--clear` carries the field as a value
/// rather than in the flag's own name. So it is checked once here and refused, rather
/// than resolved by whichever of the two happens to be applied last, which is a
/// silent answer to a contradictory call.
pub fn contested(&self) -> Option<Clearable> {
self.clear.iter().copied().find(|field| match field {
Clearable::Due => self.due.is_some(),
Clearable::Tags => !self.tags.is_empty(),
Clearable::Priority => self.priority.is_some(),
Clearable::Description => !self.description.is_empty(),
Clearable::Acceptance => !self.acceptance.is_empty(),
Clearable::Plan => !self.plan.is_empty(),
})
}
}
/// `chown` is the only writer of Owner, so clearing the field has to live here too, and
/// that is what shapes the arguments.
///
/// **`--clear` carries the ticket rather than being a bare flag.** The ticket is the
/// *second* positional, so `chown --clear 1b78a24` with a plain flag would land the
/// ticket in the user's slot, and reading it back out of there is hand-parsing what clap
/// can state outright. The typed call is the same either way; only who checks it differs.
///
/// The two forms are mutually exclusive, and each argument says so, so a call carrying
/// both is a usage error from clap rather than a decision made here.
#[derive(clap::Args)]
pub struct ChownArgs {
/// New owner. Free text, like `add --owner`, checked against nothing
#[arg(value_parser = clearable, required_unless_present = "clear", conflicts_with = "clear")]
pub user: Option<String>,
/// Ticket UUID or title
#[arg(required_unless_present = "clear", conflicts_with = "clear")]
pub ticket: Option<String>,
/// Return the owner to unset on this ticket, which is named here since there is no
/// user to name
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
pub clear: Option<String>,
/// Not the same as `user`, which is the ticket's new assignee: this is who made the
/// change. Both are on this command because it writes both.
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
}
impl ChownArgs {
/// The ticket the call names, and the owner to write on it, `None` being unset.
///
/// `None` for the pair is unreachable while the constraints above hold, and is an
/// error at the call site rather than a panic, so loosening one of them costs a
/// message instead of a crash.
pub fn target(&self) -> Option<(&str, Option<&str>)> {
match (self.clear.as_deref(), self.user.as_deref(), self.ticket.as_deref()) {
(Some(ticket), None, None) => Some((ticket, None)),
(None, Some(user), Some(ticket)) => Some((ticket, Some(user))),
_ => None,
}
}
}
/// `append` offers the fields something can be added to without disturbing what is
/// already in them: the three sections that hold multiple lines, and Tags, which is a
/// list. Appending to a scalar has no meaning, so there is no `--priority` or `--due`.
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("append_fields")
.required(true)
.multiple(true)
.args(["description", "acceptance", "plan", "tags"])
))]
pub struct AppendArgs {
/// Ticket UUID or title
pub ticket: String,
/// Add a paragraph to the description. Repeat the flag for more lines within it
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// Add acceptance criteria. Repeat the flag, one criterium per value
#[arg(short, long, allow_hyphen_values = PROSE)]
pub acceptance: Vec<String>,
/// Add implementation plan steps, numbered on from the last. Repeat the flag
#[arg(short, long, allow_hyphen_values = PROSE)]
pub plan: Vec<String>,
/// Add tags, keeping the ones the ticket already carries. Repeat the flag, or
/// separate them with commas
///
/// `non_empty` rather than the `clearable` that `set --tags` takes. That message
/// names `--clear`, and this command has none: emptying the field is
/// `set --clear tags`, so pointing at a flag that is not here would send the caller
/// looking for it on `append`.
#[arg(short = 'g', long, value_parser = non_empty)]
pub tags: Vec<String>,
/// Only reaches the entry `--tags` writes, since that is the one field of this
/// command's that is logged, exactly as on `set`
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
}
/// `relate` is the only writer of the Relations section, the way `chown` is the only
/// writer of Owner. One flag per kind rather than a `--kind` value: the accepted kinds
/// are then clap's business, an unknown one is a usage error, and a call reads as a
/// sentence about the ticket it names.
///
/// Each flag repeats, so several relations of one kind land in a single call. The
/// targets are ticket searches, resolved by the same three tiers every other ticket
/// argument is, and stored as the target's uuid.
///
/// `--clear` is the other direction, and it is here rather than on `set` for the reason
/// Relations is absent from `section_args`: a relation names a target that has to be
/// resolved first, so its one writer owns both adding and removing, the way `chown` owns
/// both setting an owner and clearing one.
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("relation_kinds")
.required(true)
.multiple(true)
.args(["blocked_by", "regression_of", "relates_to", "clear"])
))]
pub struct RelateArgs {
/// Ticket UUID or title
pub ticket: String,
/// Ticket this one waits on. Its own moves are refused until the target is done
#[arg(long, value_parser = non_empty)]
pub blocked_by: Vec<String>,
/// Ticket whose fix this one broke
#[arg(long, value_parser = non_empty)]
pub regression_of: Vec<String>,
/// Ticket this one is merely related to. Symmetric, so it is recorded once
#[arg(long, value_parser = non_empty)]
pub relates_to: Vec<String>,
/// Take a relation off: the kind, then the ticket it points at. Repeat the flag
///
/// Two values rather than one, because a ticket can hold several relations of one
/// kind and emptying every `blocked by` on it is not usually what is wanted. That is
/// also why this is not `set --clear`, which names a field and empties the whole of
/// it: the "value" here is one edge among several, so the target has to be named too.
///
/// A `Vec<String>` because clap cannot type the two values of one flag apart.
/// [`RelateArgs::cleared`] is where the pairs are split and the kind is parsed.
#[arg(long, num_args = 2, value_names = ["KIND", "TARGET"], value_parser = non_empty)]
pub clear: Vec<String>,
}
impl RelateArgs {
/// The relations asked for, one entry per kind, so the handler walks a table
/// instead of repeating itself three times.
pub fn requested(&self) -> [(RelationKind, &[String]); 3] {
[
(RelationKind::BlockedBy, &self.blocked_by),
(RelationKind::RegressionOf, &self.regression_of),
(RelationKind::RelatesTo, &self.relates_to),
]
}
/// The relations asked to be taken off, as a kind and the search naming the target.
///
/// `num_args = 2` is per occurrence, so clap has already refused an odd number of
/// values and every chunk is a full pair. A kind that is not one of the three is
/// refused here, before the ticket is resolved and long before anything is written.
pub fn cleared(&self) -> anyhow::Result<Vec<(RelationKind, &str)>> {
self.clear
.chunks(2)
.map(|pair| Ok((RelationKind::parse_value(&pair[0])?, pair[1].as_str())))
.collect()
}
}
/// `check` and `uncheck` are separate commands rather than one verb with a flag,
/// because the two read as opposites at the call site and neither needs the other's
/// name to make sense.
///
/// The criteria are optional: without any the criteria are listed and the index asked
/// for, or, where there is no terminal to ask at, returned as an error carrying the
/// same list.
///
/// Several terms in one call because finishing a ticket means ticking every box, and
/// one invocation per box resolved the ticket and rewrote the file each time. The
/// terms are variadic rather than a repeated flag: they address something that is
/// already there, the way the ticket positional does, instead of carrying content the
/// way `--acceptance` does.
#[derive(clap::Args)]
pub struct CheckArgs {
/// Ticket UUID or title
pub ticket: String,
/// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted
pub criteria: Vec<String>,
}
#[cfg(test)]
mod tests {
use super::*;
use clap::CommandFactory;
/// The command names as the README table would have to spell them: `campaign add`
/// for a nested one, the bare name for a top level one. `help` is clap's own and
/// documents nothing.
fn documented_names() -> Vec<String> {
let cli = Cli::command();
let mut names = Vec::new();
for sub in cli.get_subcommands() {
if sub.get_name() == "help" {
continue;
}
names.push(sub.get_name().to_string());
for nested in sub.get_subcommands() {
if nested.get_name() == "help" {
continue;
}
names.push(format!("{} {}", sub.get_name(), nested.get_name()));
}
}
names
}
/// Every subcommand has a row in the README's command table.
///
/// `campaign` and `assign` went undocumented for two minor versions, e6e3a1b, and
/// the `--campaign` flag went with them, because the only thing walking the table
/// was somebody remembering to. This is what walks it. A command whose row is
/// missing is a command a reader of the README cannot discover at all, which is a
/// worse failure than a row that is merely out of date.
#[test]
fn every_subcommand_has_a_row_in_the_readme_command_table() {
// The tag subcommands are f7dd1a1's, which rewrites the `worklane tags` row
// once the vocabulary work above it has landed. Listed rather than skipped, so
// emptying this is part of closing that ticket rather than something to
// rediscover.
const PENDING: [&str; 3] = ["tags add", "tags set", "tags ls"];
let readme = include_str!("../README.md");
let table: String = readme.lines().filter(|line| line.starts_with('|')).collect();
let missing: Vec<String> = documented_names()
.into_iter()
.filter(|name| !PENDING.contains(&name.as_str()))
.filter(|name| !table.contains(&format!("`worklane {}", name)))
.collect();
assert!(
missing.is_empty(),
"no row in the README command table for {missing:?}. A new command is not \
shipped until the table lists it: that table is the only place a reader \
discovers one, and two commands hid behind an otherwise complete table \
for two minor versions."
);
}
/// `--actor` and `--actor-from-git` are one pair that has to travel together: every
/// command that takes one takes the other, documented by the same string, because
/// the second is the first's spelling for "the human whose checkout this is".
///
/// A walker rather than five named commands, so a sixth entry-writing command fails
/// this on its own `--actor` instead of being forgotten here too.
#[test]
fn every_actor_command_takes_actor_from_git() {
let cli = Cli::command();
let mut seen = 0;
for sub in cli.get_subcommands() {
if sub.get_name() == "help" {
continue;
}
if !sub.get_arguments().any(|arg| arg.get_id().as_str() == "actor") {
continue;
}
seen += 1;
let from_git = sub
.get_arguments()
.find(|arg| arg.get_id().as_str() == "actor_from_git")
.unwrap_or_else(|| {
panic!("`{}` takes --actor but not --actor-from-git", sub.get_name())
});
assert_eq!(
from_git.get_help().map(|help| help.to_string()),
Some(ACTOR_FROM_GIT_HELP.to_string()),
"`{}` documents --actor-from-git differently",
sub.get_name()
);
}
// A guard on the walker itself: if it stopped finding commands, every assertion
// above would pass by never running.
assert_eq!(
seen, 6,
"expected comment, mv, chown, set, append and assign to carry --actor"
);
}
}