diff --git a/Cargo.lock b/Cargo.lock index a13eca7..7dce757 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.25.0" +version = "0.26.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 9252b98..1b05ac3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.25.0" +version = "0.26.0" edition = "2024" [dependencies] diff --git a/src/command.rs b/src/command.rs index a53bad2..af7142d 100644 --- a/src/command.rs +++ b/src/command.rs @@ -490,13 +490,14 @@ pub struct CampaignAddArgs { /// 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. /// -/// No `set`: changing an annotation is 9688d34, and a half of `add`/`set` that only ever -/// declares is the honest half to ship first. #[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, } @@ -518,6 +519,41 @@ pub struct TagAddArgs { pub annotation: Vec, } +/// 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 ` 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, +} + /// `ls` holds four filters, an output mode and nothing else, which is the boundary the /// Rust Style rule in AGENTS.md names: two of the filters are adjacent `Option` /// values that a caller can swap silently, so the mode that joined them came as a diff --git a/src/completions.rs b/src/completions.rs index c40613c..455ea72 100644 --- a/src/completions.rs +++ b/src/completions.rs @@ -66,6 +66,15 @@ pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"]; /// one where `ls --ids` answers the tickets. pub const TAG_FLAGS: [&str; 1] = ["tag"]; +/// Nested commands whose first argument is a tag the board already has. +/// +/// `tags set` changes what a declared tag means, so the values it takes are exactly the +/// ones `worklane tags` prints. `tags add` is deliberately absent: the tag it takes is one +/// the board does not have yet, so offering the ones it does would offer exactly the values +/// it refuses. Which of the two a new tag positional belongs to is what +/// `no_tag_taking_option_is_missing` makes somebody decide. +pub const TAG_NESTED_COMMANDS: [(&str, &str); 1] = [("tags", "set")]; + pub fn generate(shell: Shell, out: &mut dyn io::Write) -> io::Result<()> { let mut command = crate::command::Cli::command(); clap_complete::generate(shell, &mut command, "worklane", out); @@ -92,6 +101,11 @@ fn fish_dynamic() -> String { .join("; or "); let campaign_flags = flag_list(&CAMPAIGN_FLAGS); let tag_flags = flag_list(&TAG_FLAGS); + let tag_nested = TAG_NESTED_COMMANDS + .iter() + .map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}")) + .collect::>() + .join("; or "); let statuses = possible_values(Status::value_variants()); let shells = possible_values(Shell::value_variants()); let skills = SKILLS @@ -182,6 +196,11 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \ # worth reading: it says which spelling the board actually uses. complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)' +# And `tags set` names one that is already declared, so it reads the same listing. `tags +# add` has no rule on purpose: it takes a tag the board does not have, so the candidates +# here are the values it refuses. +complete -c worklane -n '{tag_nested}' -a '(worklane tags)' + # `chown --clear` names the ticket in the flag too, since with no user to give there is # no second positional to put it in. Scoped to `chown`, unlike the rule above: `set` # has a `--clear` of its own that takes a field name, and clap already offers those. @@ -377,16 +396,18 @@ mod tests { let name = path.join(" "); let Some(long) = arg.get_long() else { - let nested = match path.as_slice() { + let known = match path.as_slice() { [parent, child] => { - TAG_NEW_COMMANDS.contains(&(parent.as_str(), child.as_str())) + let pair = (parent.as_str(), child.as_str()); + TAG_NESTED_COMMANDS.contains(&pair) || TAG_NEW_COMMANDS.contains(&pair) } _ => false, }; assert!( - nested, - "`worklane {name}` takes a tag as a positional, \ - which the fish block has no rule for" + known, + "`worklane {name}` takes a tag as a positional, so it belongs in \ + TAG_NESTED_COMMANDS if the tag already exists and TAG_NEW_COMMANDS if it \ + does not" ); continue; }; @@ -397,7 +418,7 @@ mod tests { ); } - assert_eq!(seen, 2, "expected ls --tag and tags add"); + assert_eq!(seen, 3, "expected ls --tag, tags add and tags set"); } /// **Every rule naming an option has to say which command it belongs to.** A bare diff --git a/src/handlers.rs b/src/handlers.rs index ab126dc..15856a0 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -8,7 +8,7 @@ use std::path::Path; use crate::campaign::*; use crate::command::{ AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs, - RelateArgs, SetArgs, TagAddArgs, + RelateArgs, SetArgs, TagAddArgs, TagSetArgs, }; use crate::install; use crate::tag::{TAGS_FILE, TagIndex, tags_path}; @@ -872,12 +872,23 @@ fn apply(content: &mut String, changed: &mut Vec<&'static str>, field: &'static } fn report(fields: &[&str], title: &str, verb: &str) { + report_in(fields, title, Color::Green, verb) +} + +/// The same, for a subject that is not a title. +/// +/// Green means title, everywhere, so the one caller whose subject is a tag cannot use it: +/// a tag is drawn in a `TAG_COLORS` slot or it is drawn wrong, and green is deliberately +/// not one of them. The colour is passed in rather than decided here, which is the trade +/// `paint` makes with `color_text`, and it keeps the wording in one place so a tag reports +/// a no-op in the same words a ticket does. +fn report_in(fields: &[&str], title: &str, color: Color, verb: &str) { if fields.is_empty() { - println!("No changes to '{}'", color_text(title, Color::Green)); + println!("No changes to '{}'", color_text(title, color)); return; } - println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, Color::Green)); + println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, color)); } pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> { @@ -1296,6 +1307,53 @@ pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> { Ok(()) } +/// Replace what a declared tag means. +/// +/// The other half of `tags add`, and the half `campaign` still lacks for its description, +/// 32e98ab. An annotation is the sentence a whole team files tickets against, so getting it +/// wrong once must not be permanent. +/// +/// **A tag that is not declared is refused rather than declared here.** `add` and `set` are +/// a pair, each refusing what the other is for, so which of the two wrote a line is never a +/// question of which one happened to be typed. The refusal names the other command, the way +/// `add`'s names this one. +/// +/// The no-op compares the rendered file rather than the annotation, which is what `apply` +/// does for a ticket: the file is the thing that would be written, so it is the thing worth +/// asking whether the write would change. +pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> { + let worklane_dir = find_worklane_dir(start)?; + let mut index = TagIndex::load(&worklane_dir)?; + + if !index.declared(&args.tag) { + return Err(anyhow!( + "No tag '{}' is declared, so nothing was written. \ + Use `worklane tags add` to declare it", + args.tag + )); + } + + let original = index.render(); + index.declare(&args.tag, &trim_blank_ends(&args.annotation).join("\n")); + let next = index.render(); + + let mut changed: Vec<&'static str> = Vec::new(); + if original != next { + changed.push("annotation"); + write_then_replace( + &worklane_dir, + &tags_path(&worklane_dir), + TAGS_FILE, + &next, + TAG, + &args.tag, + )?; + } + + report_in(&changed, &args.tag, tag_color(&args.tag), "Updated"); + Ok(()) +} + /// Replace fields on a campaign that is already filed. /// /// `cmd_set` for a campaign, and built out of the same parts: `set_title` for the heading, diff --git a/src/main.rs b/src/main.rs index b3af4ab..2bfb4ab 100644 --- a/src/main.rs +++ b/src/main.rs @@ -88,6 +88,7 @@ fn main() -> Result<()> { cmd_tags(&worklane_dir) } Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start), + Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start), }, // No board either, for the reason `install-skill` has none: a completion script // is generated from the clap definition and is the same wherever it is run. diff --git a/tests/cmd_tags.rs b/tests/cmd_tags.rs index 526ed63..078a3f2 100644 --- a/tests/cmd_tags.rs +++ b/tests/cmd_tags.rs @@ -411,3 +411,126 @@ fn the_bare_form_and_ls_are_the_same_listing() { assert_eq!(bare.stdout, group.stdout); assert_eq!(String::from_utf8_lossy(&bare.stdout), "bug\t1\ncli\t1\n"); } + +// -------------------------------------------------- changing what a tag means -- + +/// The replacement lands, and replaces rather than appends. +#[test] +fn tags_set_replaces_what_a_tag_means() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]); + + let out = run(&temp, &["tags", "set", "bug", "-a", "The second sentence."]); + assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr)); + + assert_eq!(declared(&temp, "bug").as_deref(), Some("The second sentence.")); + assert!(!vocabulary(&temp).contains("first"), "the old annotation survived"); +} + +/// Paragraph breaks survive the round trip, which is the whole difference between an +/// annotation and a one-line description of a tag. +#[test] +fn a_multiline_annotation_survives_being_set() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + run(&temp, &["tags", "add", "bug"]); + + run( + &temp, + &[ + "tags", + "set", + "bug", + "-a", + "What it is.", + "-a", + "", + "-a", + "When to use it.", + ], + ); + + assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it.")); +} + +/// Set to what it already says, nothing is written and the command says so, the way `set` +/// and `chown` report a field that already holds the value. +#[test] +fn setting_an_annotation_to_what_it_already_says_writes_nothing() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + run(&temp, &["tags", "add", "bug", "-a", "The sentence."]); + + let before = fs::metadata(temp.path().join(".worklane").join("tags.md")) + .unwrap() + .modified() + .unwrap(); + + let out = run(&temp, &["tags", "set", "bug", "-a", "The sentence."]); + assert!(out.status.success()); + assert!(String::from_utf8_lossy(&out.stdout).contains("No changes"), "{out:?}"); + + let after = fs::metadata(temp.path().join(".worklane").join("tags.md")) + .unwrap() + .modified() + .unwrap(); + assert_eq!(before, after, "the file was rewritten for a no-op"); +} + +/// `add` and `set` are a pair, each refusing what the other is for, so the refusal names +/// the other command rather than leaving it to be found. +#[test] +fn setting_a_tag_that_is_not_declared_is_refused_and_names_add() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + run(&temp, &["tags", "add", "bug"]); + + let out = run(&temp, &["tags", "set", "cli", "-a", "Anything."]); + + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(stderr.contains("tags add"), "{stderr}"); + assert!(declared(&temp, "cli").is_none(), "the tag was declared by set"); +} + +/// A bare `tags set ` is a usage error. Nothing to write is a mistake in the call, not +/// a command that quietly does nothing. +#[test] +fn setting_nothing_is_a_usage_error() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + run(&temp, &["tags", "add", "bug", "-a", "The sentence."]); + + let out = run(&temp, &["tags", "set", "bug"]); + + assert_eq!(out.status.code(), Some(2), "{out:?}"); + assert_eq!(declared(&temp, "bug").as_deref(), Some("The sentence.")); +} + +/// An annotation can be emptied back to the placeholder, which is the state a tag declared +/// without one is already in. That is why there is no `--clear`. +#[test] +fn an_annotation_can_be_emptied_back_to_the_placeholder() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + run(&temp, &["tags", "add", "bug", "-a", "The sentence."]); + + run(&temp, &["tags", "set", "bug", "-a", ""]); + + assert_eq!(declared(&temp, "bug").as_deref(), Some("_No annotation provided._")); +} + +/// The other tags keep their sections, since the whole file is re-rendered on every write. +#[test] +fn setting_one_annotation_leaves_the_others_alone() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + run(&temp, &["tags", "add", "bug", "-a", "About bugs."]); + run(&temp, &["tags", "add", "tui", "-a", "About the board."]); + + run(&temp, &["tags", "set", "bug", "-a", "Rewritten."]); + + assert_eq!(declared(&temp, "bug").as_deref(), Some("Rewritten.")); + assert_eq!(declared(&temp, "tui").as_deref(), Some("About the board.")); +}