diff --git a/AGENTS.md b/AGENTS.md index 59a8e0d..c0b8459 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,16 +87,20 @@ and this file is for what someone changing worklane's own code needs. - **Two halves, and the split is the point.** `clap_complete` generates the structure from the clap definition, so a new flag or subcommand is completed without anyone touching `completions.rs`. Only fish gets the second half, appended by `fish_dynamic()`, and it holds exactly what clap cannot know: the tickets on the board - **The dynamic values come from worklane itself**, as `worklane ls --ids` in a command substitution, one run per keypress at 2.5ms in release. So the completions are only as current as the binary on PATH: an older one without `--ids` completes nothing, which is a reinstall rather than a bug - **What clap does and does not emit.** It emits the possible values of an *option*, which is why `mv --status ` needs nothing here, and nothing for a *positional*, which is why the `ls` status and the `completions` shell are listed in the fish half. Both lists are read off the enums with `possible_values`, never written out, so a fifth status appears in the script on its own -- **Position is counted, not inferred.** `__worklane_first_arg_of` and `__worklane_second_arg_of` check `$tokens[2]` and the token count rather than using `__fish_seen_subcommand_from`, because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, and because matching against the ticket list would run worklane again inside the condition -- **`TICKET_COMMANDS`, `TICKET_SECOND_COMMANDS` and `TICKET_FLAGS` are kept honest by tests**, which walk the clap definition and fail on a ticket-taking subcommand that is in neither list, or in the list for the wrong position. A nested subcommand is not walked: `campaign` is the only one, none of its three takes a ticket, and the token counting could not tell them apart if one did -- **`ls --ids` is the machine-readable listing**, and the only output in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads `cut -f1`. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown `--campaign` is still refused +- **Position is counted, not inferred.** The four `__worklane_*` predicates all read `$tokens[2]` and the token count rather than using `__fish_seen_subcommand_from`, because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, and because matching against the ticket list would run worklane again inside the condition. `first_arg_of` and `second_arg_of` count a top-level command's arguments, `nested_arg_of` matches a parent and a child so `campaign show ` can be told from `chown alice `, which sit at the same token count, and `command_is` asks only which command this is, at any position in it +- **Every rule carrying `-l` needs a `__worklane_command_is`, and `every_rule_naming_an_option_is_scoped_to_a_command` is what enforces it.** A bare `complete -c worklane -l tag` does not just complete that option's values, it tells fish the whole tool accepts `--tag`: `worklane init --` offered six options that only `relate` and `ls` have. Fixed in 55ee6e3. `__fish_seen_subcommand_from ls` is not the scope to use, for the nesting reason above +- **The five completion lists are kept honest by tests** that walk the clap definition and fail on an argument left out of them. `TICKET_COMMANDS` and `TICKET_SECOND_COMMANDS` by position, `TICKET_FLAGS`, `CAMPAIGN_COMMANDS`, `CAMPAIGN_NESTED_COMMANDS`, `CAMPAIGN_FLAGS` and `TAG_FLAGS` likewise. The walk is one function, `every_argument`, since the tests differ only in the id they look for. Each also asserts *how many* it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them +- **A campaign is named in three shapes and a tag in one**, which is why the lists are not one list: a campaign is `assign`'s first positional, `campaign show`'s only argument and `ls --campaign`'s value, and each needs a different fish rule. A tag is only ever an option value, and its values come from a different command +- **`ls --ids` is the machine-readable listing**, and one of the three outputs in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads `cut -f1`. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown `--campaign` is still refused +- **`campaign ls --ids` is the same flag and the same two fields for the other object**, and it deliberately skips the member counting the decorated listing does: `members()` reads every ticket on the board, and the caller here is a shell filling in candidates on a keypress. It also prints nothing on an empty board, where the decorated listing prints a sentence, because a sentence offered as a candidate is worse than no candidates +- **`worklane tags` is the third, and it is a command rather than a mode on `ls`.** Two reasons: `ls --tag ` answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a `--tags` beside a `--tag` is one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, so `bug` and `Bug` list separately and land next to each other, which is where a near-duplicate is spotted. Every status, done included: a tag that has fallen out of use is still part of what the vocabulary has been. `assets/PLAN.md` used to tell the agent to count tags with a `show` per ticket, and now points here ### Filtering the Listing - **The filters are one call, `filtered`,** because `ls` collects a column in three places (a named status, the counts, and the grouped listing) and three call sites are three chances to apply a different set. Every filter is an `Option` and none asked for keeps everything, which is what makes them compose in any combination without a rule per pair - **`--tag` matches whole values, not the field.** `parse_tags` has already split the comma-separated field, so the filter compares against those trimmed values: `--tag bug` is not answered by a ticket tagged `bugfix`, and `--tag "cli, filter"` matches nothing, because the field as written is not itself a tag. A ticket with no tags matches none - **Case sensitive**, the opinion the field already takes: `tag_color` draws `Bug` and `bug` in two colours because they are two tags. A filter that folded them would list tickets carrying a tag nobody asked for, and would hide exactly the split a grooming sweep is looking for - **One tag per invocation.** Several would have to decide between and and or, and neither reading is obviously right for a board this size. That decision is its own ticket, along with a substring or regex match and a tag filter on the tui -- **A tag nothing carries lists nothing rather than being refused**, which is the opposite of `--campaign`. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. `assets/PLAN.md` tells the agent to check the spelling when a listing comes back empty, since that is the failure this trades for +- **A tag nothing carries lists nothing rather than being refused**, which is the opposite of `--campaign`. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. `assets/PLAN.md` tells the agent to check the spelling when a listing comes back empty, and `worklane tags` is what it checks against, since that is the failure this trades for - An emptied status keeps the message `ls` already gives, `No tickets in '' status.`, rather than one per filter naming what excluded them. That is pre-existing behaviour for `--priority` and `--campaign`, and one message for every filter is the consistent half of it. If it should name the filter, that is a change to what the CLI prints for three flags at once and belongs in its own ticket - **`cmd_ls` takes an `LsArgs`**, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacent `Option` values a caller could swap silently. `--ids` was the argument that tipped it, the way `add` became `AddArgs`. A new filter is a field there, not a parameter diff --git a/Cargo.lock b/Cargo.lock index 0fc9123..d9f86c5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.18.1" +version = "0.19.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 8ee482d..d6ef38b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.18.1" +version = "0.19.0" edition = "2024" [dependencies] diff --git a/README.md b/README.md index d357fd6..bed1582 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ Worklane is a local Kanban flow for agentic software development. | `worklane check [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal | | `worklane uncheck [criteria...]` | Unticks acceptance criteria, addressed the same way | | `worklane comment ` | Adds a comment to a ticket by UUID or title | +| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known | | `worklane completions ` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below | | `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills//SKILL.md`, which Claude Code and opencode both read. Three ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name | @@ -39,10 +40,14 @@ worklane mv the same, then --status for the four worklane chown alice the ticket, which is the second argument here worklane chown --clear the ticket, which the flag carries here worklane relate x --blocked-by +worklane campaign show the campaigns, from `campaign ls --ids` +worklane assign the same, since a campaign comes first here +worklane ls --campaign and again +worklane ls --tag the tags, from `worklane tags`, with their counts ``` -The tickets come from `worklane ls --ids`, one run per keypress, 2.5ms in release on a board of -seventy-five tickets. Since fish runs whatever `worklane` is on PATH, **completions need the +The tickets come from `worklane ls --ids`, the campaigns from `worklane campaign ls --ids` and the tags +from `worklane tags`, one run per keypress, 2.5ms in release on a board of seventy-five tickets. Since fish runs whatever `worklane` is on PATH, **completions need the installed binary to be current**: an older one without `--ids` completes nothing. Re-run `cargo install --path .` after pulling. diff --git a/assets/PLAN.md b/assets/PLAN.md index a759629..bad8529 100644 --- a/assets/PLAN.md +++ b/assets/PLAN.md @@ -58,16 +58,17 @@ worklane ls # every status, counts then tickets worklane ls backlog # one status worklane ls --priority 1 # the top of the pile worklane ls --tag bug # one tag's worth of the board +worklane tags # the whole vocabulary, with counts worklane show 1b78a24 # one ticket, with its relations and comments worklane campaign ls # the goals that already exist ``` -`ls` prints the mark, the id, the title, the owner and the due date. It does **not** -print tags, so the vocabulary itself still has to be read off the tickets: `--tag` answers -"what is tagged `bug`" and cannot answer "what tags exist", which is the question a -grooming sweep starts from. Count the vocabulary with a `show` per ticket, then use -`--tag` to check each candidate, and remember that `--tag` matches whole values case -sensitively: `bug` and `Bug` are two answers, which is exactly the split worth reporting. +`ls` prints the mark, the id, the title, the owner and the due date, and **not** the tags. +So the vocabulary comes from `worklane tags`, which is the one command that answers what +tags exist rather than what carries a tag you already know. One line per tag, alphabetical, +as the tag, a tab and its count. It is case sensitive like the filter, so `bug` and `Bug` +list separately and, being alphabetical, land next to each other, which is where a +near-duplicate is spotted. Start a tag sweep there rather than with a `show` per ticket. Read `done` too when the question is about what to do next. What was finished last is the best evidence of what this board actually moves at, and a plan that ignores it is a wish. @@ -131,7 +132,11 @@ field**. Restate every tag the ticket should keep, or the ones you left out are This is the single most destructive thing in this document. `--clear tags` empties the field on purpose, which is a different thing from emptying it by forgetting a tag. -Derive the vocabulary from the board rather than inventing one. Read the tickets, count +`worklane tags` before and after a tag sweep is the cheapest check that it did what was +proposed: a count that dropped where nothing was meant to change is a tag lost to the +replace-the-whole-field rule above. + +Derive the vocabulary from the board rather than inventing one. Read `worklane tags`, count what is actually used, and show the count before proposing anything. What to report: - **Two spellings of one idea.** `bug` and `bugfix`, `tui` and `ui`. Pick the one already diff --git a/assets/SKILL.md b/assets/SKILL.md index 5f4870f..0280d43 100644 --- a/assets/SKILL.md +++ b/assets/SKILL.md @@ -65,6 +65,12 @@ against the whole values of the comma-separated `Tags` field, case sensitively, tags matches none. A tag nothing carries lists nothing rather than failing, so when a listing comes back empty check the spelling against a ticket you know is tagged. +`worklane tags` answers the other question, the one `--tag` cannot: **what tags exist**. +One line per tag, alphabetical, as the tag, a tab and how many tickets carry it. Case +sensitive, like the filter, so `bug` and `Bug` list separately and land next to each +other, which is where a near-duplicate is spotted. Read it before inventing a tag, and +read it when a `--tag` filter comes back emptier than expected. + ## Working a ticket ``` @@ -203,6 +209,7 @@ there is no such thing as a done campaign holding an open ticket. worklane campaign add --title "v1 release" \ --description "Everything that has to ship before the tag." worklane campaign ls # every campaign and how far it has got +worklane campaign ls --ids # id and title, tab separated, like ls --ids worklane campaign show "v1 release" # its body, then its members by status worklane assign "v1 release" 1b78a24 # put a ticket in it worklane ls --campaign "v1 release" # only that campaign's tickets diff --git a/src/command.rs b/src/command.rs index ad13bf1..5013978 100644 --- a/src/command.rs +++ b/src/command.rs @@ -223,6 +223,16 @@ pub enum Command { ticket: String, }, + /// List the tags the board carries, and how many tickets carry each + /// + /// A command rather than a mode on `ls`, for two reasons. `ls --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 output is machine-readable, like `ls --ids`: the tag, a tab, the count. + Tags, + /// Print a shell completion script /// /// The structure comes from the clap definition, so a flag added here appears @@ -263,7 +273,17 @@ pub enum CampaignCommand { Add(CampaignAddArgs), /// List campaigns with their member counts - Ls, + 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 { diff --git a/src/completions.rs b/src/completions.rs index 0dfa822..471b509 100644 --- a/src/completions.rs +++ b/src/completions.rs @@ -42,6 +42,30 @@ pub const TICKET_SECOND_COMMANDS: [&str; 2] = ["chown", "assign"]; /// Options whose value is a ticket, as `relate` takes three of. pub const TICKET_FLAGS: [&str; 3] = ["blocked-by", "regression-of", "relates-to"]; +/// Subcommands whose first positional is a campaign. +/// +/// `assign` alone, which takes the campaign first and the ticket second. Kept honest by +/// the same test the ticket lists are. +pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"]; + +/// Nested subcommands whose first argument is a campaign, as `parent child`. +/// +/// `campaign show` is the only one, and it is why the fish half needs a third position +/// helper: its argument is the *third* token, where `__worklane_first_arg_of` reads the +/// second and `__worklane_second_arg_of` counts a top-level command's arguments. Neither +/// can tell `campaign show ` from `chown alice ` by position. +pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 1] = [("campaign", "show")]; + +/// Options whose value is a campaign. +pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"]; + +/// Options whose value is a tag. +/// +/// Its own list rather than a line in the block below, because the values come from a +/// different command: a tag is not an object with an id, so `worklane tags` answers this +/// one where `ls --ids` answers the tickets. +pub const TAG_FLAGS: [&str; 1] = ["tag"]; + 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); @@ -59,11 +83,15 @@ pub fn generate(shell: Shell, out: &mut dyn io::Write) -> io::Result<()> { fn fish_dynamic() -> String { let ticket_commands = TICKET_COMMANDS.join(" "); let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" "); - let ticket_flags = TICKET_FLAGS + let ticket_flags = flag_list(&TICKET_FLAGS); + let campaign_commands = CAMPAIGN_COMMANDS.join(" "); + let campaign_nested = CAMPAIGN_NESTED_COMMANDS .iter() - .map(|flag| format!("-l {flag}")) + .map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}")) .collect::>() - .join(" "); + .join("; or "); + let campaign_flags = flag_list(&CAMPAIGN_FLAGS); + let tag_flags = flag_list(&TAG_FLAGS); let statuses = possible_values(Status::value_variants()); let shells = possible_values(Shell::value_variants()); let skills = SKILLS @@ -87,7 +115,7 @@ complete -c worklane -f # The exception, and the reason the line above is not the whole story: `tui` takes # project paths, as many as you like. Directories only, since each is resolved to the # first `.worklane` at or above it. -complete -c worklane -n '__fish_seen_subcommand_from tui' \ +complete -c worklane -n '__worklane_command_is tui' \ -a '(__fish_complete_directories)' -d project # Position is counted rather than inferred from what has been typed: matching against @@ -108,6 +136,28 @@ function __worklane_second_arg_of test (count $tokens) -eq 3; and contains -- $tokens[2] $argv end +# The first argument of a nested subcommand, `worklane campaign show `. Three tokens +# with both names matched, rather than the token counting the two above do: `campaign show` +# puts its argument where a top-level command puts its second, so counting alone would +# offer campaigns to `chown alice ` and tickets here. +function __worklane_nested_arg_of + set -l tokens (commandline -opc) + test (count $tokens) -eq 3; and test "$tokens[2]" = "$argv[1]"; and test "$tokens[3]" = "$argv[2]" +end + +# Which command this is, at any position in it. `$tokens[2]` again rather than +# `__fish_seen_subcommand_from`, and for the reason spelled out above: `campaign ls` is an +# `ls` that fish has seen, so scoping `--tag` with fish's own helper would offer it under a +# command that does not take it. +# +# A rule carrying `-l` needs one of these. Without it fish takes the option as one the +# whole tool accepts, and `worklane init --` offered `--blocked-by`, `--tag` and four +# others that only `relate` and `ls` have. +function __worklane_command_is + set -l tokens (commandline -opc) + test (count $tokens) -ge 2; and contains -- $tokens[2] $argv +end + # No `-d`: `ls --ids` prints the id and the title separated by a tab, which is fish's # own form for a candidate and its description, so every ticket carries its own. complete -c worklane \ @@ -116,12 +166,26 @@ complete -c worklane \ # `relate` takes its targets as option values, so they are completed by flag rather # than by position. -complete -c worklane {ticket_flags} -x -a '(worklane ls --ids)' +complete -c worklane -n '__worklane_command_is relate' {ticket_flags} \ + -x -a '(worklane ls --ids)' + +# Campaigns, from `campaign ls --ids`, in the three places one is named: `assign`'s first +# argument, `campaign show`'s only one, and `ls --campaign`. +complete -c worklane \ + -n '__worklane_first_arg_of {campaign_commands}; or {campaign_nested}' \ + -a '(worklane campaign ls --ids)' +complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \ + -x -a '(worklane campaign ls --ids)' + +# Tags come from `worklane tags` rather than from a listing of objects, since a tag has no +# id. The count after the tab lands as fish's description, which is what makes the list +# worth reading: it says which spelling the board actually uses. +complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -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. -complete -c worklane -n '__fish_seen_subcommand_from chown' -l clear -x -a '(worklane ls --ids)' +complete -c worklane -n '__worklane_command_is chown' -l clear -x -a '(worklane ls --ids)' # clap emits the four for `mv --status`, which is an option, but the fish generator # emits nothing for the possible values of a positional. So the one place a status is @@ -136,6 +200,15 @@ complete -c worklane -n '__worklane_first_arg_of install-skill' -a '{skills}' -d ) } +/// Option names as fish wants them on a `complete` line, `-l one -l two`. +fn flag_list(flags: &[&str]) -> String { + flags + .iter() + .map(|flag| format!("-l {flag}")) + .collect::>() + .join(" ") +} + /// The names a `ValueEnum` accepts, for a fish `-a` list. /// /// Read off the enum rather than written out, so a status or a shell added to either one @@ -162,29 +235,68 @@ mod tests { cli } + /// Every argument in the tool, as the path that reaches it and the argument itself. + /// + /// One walker for the honesty tests below, rather than each one repeating the + /// traversal: they differ only in which id they are looking for. Two levels, which is + /// as deep as the tool goes, and `help` is skipped because clap generates it and it + /// takes no object of ours. + fn every_argument() -> Vec<(Vec, clap::Arg)> { + let cli = command(); + let mut found = Vec::new(); + + for subcommand in cli.get_subcommands() { + let name = subcommand.get_name().to_string(); + if name == "help" { + continue; + } + for arg in subcommand.get_arguments() { + found.push((vec![name.clone()], arg.clone())); + } + for nested in subcommand.get_subcommands() { + let child = nested.get_name().to_string(); + if child == "help" { + continue; + } + for arg in nested.get_arguments() { + found.push((vec![name.clone(), child.clone()], arg.clone())); + } + } + } + + found + } + /// Every subcommand that takes a ticket must be listed, at the position it takes it, /// or it silently loses completion. /// - /// The nested subcommands are not walked. `campaign` is the only one, none of its - /// three takes a ticket, and the token counting above could not tell them apart if - /// one did. A ticket argument added under `campaign` needs the fish block reworked, - /// not another name in a list. + /// Nested subcommands are walked now that `__worklane_nested_arg_of` exists, but + /// nothing under `campaign` takes a ticket, so a nested one is a panic rather than a + /// list: it would need a rule of its own in the fish block, and a name in a list here + /// would look like it already had one. #[test] fn no_ticket_taking_subcommand_is_missing() { - for subcommand in command().get_subcommands() { - let name = subcommand.get_name(); - for positional in subcommand.get_positionals() { - // `show` calls it `id`; everything else calls it `ticket`. - if !matches!(positional.get_id().as_str(), "ticket" | "id") { - continue; - } - match positional.get_index() { + for (path, arg) in every_argument() { + // `show` calls it `id`; everything else calls it `ticket`. + if !matches!(arg.get_id().as_str(), "ticket" | "id") { + continue; + } + let name = path.join(" "); + if arg.is_positional() { + assert_eq!( + path.len(), + 1, + "`worklane {name}` takes a nested ticket argument, \ + which needs a rule in the fish block" + ); + let top = path[0].as_str(); + match arg.get_index() { Some(1) => assert!( - TICKET_COMMANDS.contains(&name), + TICKET_COMMANDS.contains(&top), "`worklane {name}` takes a ticket first but is not in TICKET_COMMANDS" ), Some(2) => assert!( - TICKET_SECOND_COMMANDS.contains(&name), + TICKET_SECOND_COMMANDS.contains(&top), "`worklane {name}` takes a ticket second but is not in \ TICKET_SECOND_COMMANDS" ), @@ -194,6 +306,97 @@ mod tests { } } + /// The same for campaigns, which is why the lists above are three rather than one: + /// a campaign is named as a first positional, as a nested subcommand's only argument, + /// and as an option value, and each needs a different rule in the fish block. + #[test] + fn no_campaign_taking_argument_is_missing() { + let mut seen = 0; + for (path, arg) in every_argument() { + if arg.get_id().as_str() != "campaign" { + continue; + } + seen += 1; + let name = path.join(" "); + + if let Some(long) = arg.get_long() { + assert!( + CAMPAIGN_FLAGS.contains(&long), + "`worklane {name} --{long}` takes a campaign but is not in CAMPAIGN_FLAGS" + ); + continue; + } + + assert_eq!( + arg.get_index(), + Some(1), + "`worklane {name}` takes a campaign somewhere the fish block has no rule for" + ); + + match path.as_slice() { + [top] => assert!( + CAMPAIGN_COMMANDS.contains(&top.as_str()), + "`worklane {name}` takes a campaign first but is not in CAMPAIGN_COMMANDS" + ), + [parent, child] => assert!( + CAMPAIGN_NESTED_COMMANDS.contains(&(parent.as_str(), child.as_str())), + "`worklane {name}` takes a campaign but is not in CAMPAIGN_NESTED_COMMANDS" + ), + _ => panic!("`worklane {name}` is nested deeper than the fish block goes"), + } + } + + // A guard on the walker itself: if it stopped finding arguments, every assertion + // above would pass by never running. + assert_eq!(seen, 3, "expected assign, campaign show and ls --campaign"); + } + + /// Tags have their own list because their values come from `worklane tags` rather than + /// from a listing of objects, so a second tag-taking option would need that rule and + /// not the campaign one. + #[test] + fn no_tag_taking_option_is_missing() { + let mut seen = 0; + for (path, arg) in every_argument() { + if arg.get_id().as_str() != "tag" { + continue; + } + seen += 1; + let name = path.join(" "); + let long = arg.get_long().unwrap_or_else(|| { + panic!( + "`worklane {name}` takes a tag as a positional, \ + which the fish block has no rule for" + ) + }); + assert!( + TAG_FLAGS.contains(&long), + "`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS" + ); + } + + assert_eq!(seen, 1, "expected ls --tag"); + } + + /// **Every rule naming an option has to say which command it belongs to.** A bare + /// `complete -c worklane -l tag` tells fish the whole tool takes `--tag`, so + /// `worklane init --` offered six options that only `relate` and `ls` have. This + /// is what stops the next rule being written the same way. + #[test] + fn every_rule_naming_an_option_is_scoped_to_a_command() { + let script = fish_dynamic(); + // Rules are one logical line, continued with a trailing backslash. + for rule in script.replace("\\\n", " ").lines() { + if !rule.starts_with("complete") || !rule.contains("-l ") { + continue; + } + assert!( + rule.contains("__worklane_command_is"), + "this rule declares an option for the whole tool: {rule}" + ); + } + } + #[test] fn every_listed_command_is_a_real_subcommand() { let cli = command(); @@ -212,7 +415,7 @@ mod tests { .lines() .find(|line| line.starts_with("complete") && line.contains("-l clear")) .expect("chown --clear has a rule of its own"); - assert!(rule.contains("__fish_seen_subcommand_from chown"), "{rule}"); + assert!(rule.contains("__worklane_command_is chown"), "{rule}"); assert!(rule.contains("worklane ls --ids"), "{rule}"); let chown = command().find_subcommand("chown").expect("chown exists").clone(); assert!( @@ -256,6 +459,18 @@ mod tests { assert!(script.contains("worklane-review")); } + /// The two listings the campaign and tag rules read, which are separate commands + /// because a campaign has an id and a tag does not. + #[test] + fn the_fish_script_asks_worklane_for_its_campaigns_and_tags() { + let script = fish_dynamic(); + assert!(script.contains("worklane campaign ls --ids"), "{script}"); + assert!(script.contains("worklane tags"), "{script}"); + // The nested position, which neither of the two counting helpers can reach. + assert!(script.contains("__worklane_nested_arg_of campaign show"), "{script}"); + assert!(script.contains("__worklane_first_arg_of assign"), "{script}"); + } + /// The one status positional and the one shell positional, which clap does not emit /// possible values for. Read off the enums, so a fifth status would appear here on /// its own. diff --git a/src/handlers.rs b/src/handlers.rs index e51aa74..b67057a 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -1,5 +1,6 @@ use anyhow::{Result, anyhow}; use chrono::Local; +use std::collections::BTreeMap; use std::fs; use std::io::{BufRead, IsTerminal, Write}; use std::path::Path; @@ -1070,9 +1071,19 @@ pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path) -> Result<()> { /// scan per row rather than one scan reused, and it is deliberate: the alternative is a /// map from campaign uuid to counts built in a single walk, which is worth writing when /// a board has enough campaigns to notice and is premature now. -pub fn cmd_campaign_ls(worklane_dir: &Path) -> Result<()> { +pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> { let index = CampaignIndex::load(worklane_dir)?; + // Ahead of the empty check, which prints prose: a completion must offer nothing + // rather than offer a sentence, the same bargain `list_ids` takes with a missing + // status directory. + if ids { + for campaign in index.iter() { + println!("{}\t{}", short_id(&campaign.uuid), campaign.title); + } + return Ok(()); + } + if index.is_empty() { println!("No campaigns yet. `worklane campaign add --title` files one."); return Ok(()); @@ -1100,6 +1111,48 @@ pub fn cmd_campaign_ls(worklane_dir: &Path) -> Result<()> { Ok(()) } +/// Every tag on the board, with how many tickets carry it. +/// +/// The vocabulary itself, which nothing else could answer: `ls --tag` filters by a tag +/// already known, and the decorated listing does not print tags at all. A grooming sweep +/// starts by asking what the vocabulary *is*, and `assets/PLAN.md` used to have to say +/// that the question could only be answered by reading the tickets. +/// +/// **Alphabetical, and case sensitive.** `--tag` matches a whole value case sensitively, +/// so `bug` and `Bug` are two tags and listing them as one would hide the reason a filter +/// came back short. Sorting puts them next to each other, which is where a near-duplicate +/// is spotted. +/// +/// Machine-readable, the second output in the tree that is: the tag, a tab, the count. +/// Fish reads what follows the tab as a description, a script takes `cut -f1`, and neither +/// wants an escape sequence. Every status, done included, for the reason `ls --ids` +/// includes it: a tag retired months ago is still part of the answer to what the +/// vocabulary has been. +pub fn cmd_tags(worklane_dir: &Path) -> Result<()> { + // BTreeMap rather than a sort afterwards: the order is the point, and the counting + // wants a map anyway. + let mut counts: BTreeMap = BTreeMap::new(); + + for status in status_dirs() { + let status_path = worklane_dir.join(status); + // Skipped rather than refused, as in `list_ids`, and for the same reason. + if !status_path.exists() { + continue; + } + for item in collect_ticket_items(&status_path)? { + for tag in item.tags { + *counts.entry(tag).or_default() += 1; + } + } + } + + for (tag, count) in counts { + println!("{}\t{}", tag, count); + } + + Ok(()) +} + /// Show a campaign, then its members grouped by status. /// /// Every status is shown, done included, unlike `ls`, which leaves done out of its diff --git a/src/main.rs b/src/main.rs index a785ad0..34117d5 100644 --- a/src/main.rs +++ b/src/main.rs @@ -67,9 +67,9 @@ fn main() -> Result<()> { } Some(Command::Campaign { command }) => match command { CampaignCommand::Add(args) => cmd_campaign_add(&args, &start), - CampaignCommand::Ls => { + CampaignCommand::Ls { ids } => { let worklane_dir = find_worklane_dir(&start)?; - cmd_campaign_ls(&worklane_dir) + cmd_campaign_ls(&worklane_dir, ids) } CampaignCommand::Show { campaign } => { let worklane_dir = find_worklane_dir(&start)?; @@ -77,6 +77,10 @@ fn main() -> Result<()> { } }, Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start), + Some(Command::Tags) => { + let worklane_dir = find_worklane_dir(&start)?; + cmd_tags(&worklane_dir) + } // 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. Some(Command::Completions { shell }) => { diff --git a/tests/cmd_campaign.rs b/tests/cmd_campaign.rs index e972057..bf197d0 100644 --- a/tests/cmd_campaign.rs +++ b/tests/cmd_campaign.rs @@ -413,6 +413,47 @@ fn campaign_ls_lists_campaigns_with_their_member_counts() { assert!(listing.contains("v2 release | no members"), "{listing}"); } +/// The machine-readable listing, the same two fields and the same shape as `ls --ids`. +#[test] +fn campaign_ls_ids_prints_the_id_and_the_title_tab_separated() { + let temp = TempDir::new().unwrap(); + let _worklane = board(&temp); + + run(&temp, &["assign", "v1 release", MEMBER]); + + let out = run(&temp, &["campaign", "ls", "--ids"]); + assert!(out.status.success(), "{}", stderr(&out)); + + let listing = stdout(&out); + assert_eq!( + listing.lines().collect::>(), + vec![ + format!("{}\tv1 release", &CAMP_A[..7]), + format!("{}\tv2 release", &CAMP_B[..7]), + ] + ); + + // Nothing decorated: no heading, no member count, no escape. + assert!(!listing.contains("Campaigns:"), "{listing}"); + assert!(!listing.contains("done"), "{listing}"); + assert!(!listing.contains('\u{1b}'), "{listing}"); +} + +/// A completion offers nothing rather than a sentence, so the empty case that prints +/// prose for a reader has to stay out of the parsed path. +#[test] +fn campaign_ls_ids_says_nothing_on_a_board_with_no_campaigns() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + let out = run(&temp, &["campaign", "ls", "--ids"]); + assert!(out.status.success(), "{}", stderr(&out)); + assert_eq!(stdout(&out), ""); + + // The decorated listing still explains itself. + assert!(stdout(&run(&temp, &["campaign", "ls"])).contains("No campaigns yet")); +} + /// A campaign is done when it holds members and every one of them is done. An empty one /// is neither, which is why it reads `no members` rather than `0/0 done`. #[test] diff --git a/tests/cmd_tags.rs b/tests/cmd_tags.rs new file mode 100644 index 0000000..18be946 --- /dev/null +++ b/tests/cmd_tags.rs @@ -0,0 +1,177 @@ +//! `worklane tags`, the tag vocabulary. +//! +//! The command exists because `--tag` answers what carries a tag and cannot answer what +//! tags exist, which is the question a grooming sweep starts from. So the properties +//! under test are the ones that question needs: every status counted, case kept apart, +//! alphabetical order, and an output a shell can parse. + +use assert_cmd::Command; +use assert_fs::TempDir; +use assert_fs::fixture::{PathChild, PathCreateDir}; +use std::fs; +use std::path::{Path, PathBuf}; + +const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane"); + +fn setup_worklane(temp: &TempDir) -> PathBuf { + let worklane = temp.child(".worklane"); + worklane.create_dir_all().unwrap(); + + for dir in ["backlog", "committed", "reviewing", "done"] { + worklane.child(dir).create_dir_all().unwrap(); + } + + worklane.path().to_path_buf() +} + +/// A ticket carrying `tags` verbatim, so a test can write the field the way a hand-made +/// ticket would: spaced, unspaced, unset or absent. +fn create_ticket(worklane: &Path, status: &str, uuid: &str, tags: &str) { + let path = worklane.join(status).join(format!("{uuid}_ticket.md")); + fs::write( + &path, + format!( + "# Ticket {uuid}\n\ + \n\ + ## Description\n\ + Prose that says **Tags**: not-a-field, in the body.\n\ + \n\ + ## Metadata\n\ + \n\ + - **ID**: {uuid}\n\ + - **Priority**: 3\n\ + - **Tags**: {tags}\n\ + - **Owner**: alice\n\ + - **Created At**: 2026-08-21 02:10:17\n\ + - **Status**: {status}\n" + ), + ) + .unwrap(); +} + +fn run(temp: &TempDir, args: &[&str]) -> std::process::Output { + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()).args(args); + cmd.assert().get_output().clone() +} + +fn tags(temp: &TempDir) -> Vec { + let out = run(temp, &["tags"]); + assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr)); + String::from_utf8_lossy(&out.stdout) + .lines() + .map(str::to_string) + .collect() +} + +/// Every status, done included, and the count is tickets rather than mentions. +#[test] +fn tags_counts_every_tag_on_the_board() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket(&worklane, "backlog", "11111111", "bug, cli"); + create_ticket(&worklane, "committed", "22222222", "bug,tui"); + create_ticket(&worklane, "done", "33333333", "bug"); + + assert_eq!(tags(&temp), vec!["bug\t3", "cli\t1", "tui\t1"]); +} + +/// Alphabetical, which is the property that makes a near-duplicate findable: the two +/// spellings land next to each other. +#[test] +fn tags_are_alphabetical_so_near_duplicates_are_adjacent() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket(&worklane, "backlog", "11111111", "tui,bug,bugfix,cli"); + + assert_eq!(tags(&temp), vec!["bug\t1", "bugfix\t1", "cli\t1", "tui\t1"]); +} + +/// Case sensitive, like the `--tag` filter. Folding the two together here would hide the +/// reason a filter came back short. +#[test] +fn tags_keeps_case_apart_the_way_the_filter_does() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket(&worklane, "backlog", "11111111", "bug"); + create_ticket(&worklane, "backlog", "22222222", "Bug"); + + assert_eq!(tags(&temp), vec!["Bug\t1", "bug\t1"]); + + // And the filter agrees with the listing, which is the point of keeping them apart. + let filtered = String::from_utf8_lossy(&run(&temp, &["ls", "--tag", "bug", "--ids"]).stdout) + .lines() + .count(); + assert_eq!(filtered, 1); +} + +/// An unset field, an absent one and a field of separators are all no tags, the same +/// three cases `parse_tags` folds together. +#[test] +fn tags_ignores_a_ticket_with_nothing_to_count() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket(&worklane, "backlog", "11111111", "_None_"); + create_ticket(&worklane, "backlog", "22222222", " , ,"); + create_ticket(&worklane, "backlog", "33333333", ""); + // No Tags field at all, the way a hand-made ticket can be. + fs::write( + worklane.join("backlog").join("44444444_bare.md"), + "# Bare\n\n## Metadata\n\n- **ID**: 44444444\n- **Status**: backlog\n", + ) + .unwrap(); + create_ticket(&worklane, "backlog", "55555555", "real"); + + assert_eq!(tags(&temp), vec!["real\t1"]); +} + +/// A board with no tags prints nothing rather than a sentence, since a completion reads +/// this and a sentence would become a candidate. +#[test] +fn tags_says_nothing_on_a_board_with_no_tags() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + let out = run(&temp, &["tags"]); + assert!(out.status.success()); + assert_eq!(String::from_utf8_lossy(&out.stdout), ""); +} + +/// Unstyled, like `ls --ids`: a shell reads this and an escape sequence would land in +/// the candidate. +#[test] +fn tags_is_unstyled() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog", "11111111", "bug"); + + let listing = String::from_utf8_lossy(&run(&temp, &["tags"]).stdout).to_string(); + assert!(!listing.contains('\u{1b}'), "{listing:?}"); +} + +/// The Tags line in a Description is prose, not a field, the same rule every other +/// metadata read follows. +#[test] +fn tags_reads_only_the_metadata_section() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog", "11111111", "bug"); + + assert_eq!(tags(&temp), vec!["bug\t1"]); +} + +/// A missing status directory is skipped rather than refused, as in `ls --ids`: the +/// caller is usually a shell, and an error over the prompt is worse than fewer answers. +#[test] +fn tags_skips_a_missing_status_directory() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + create_ticket(&worklane, "backlog", "11111111", "bug"); + fs::remove_dir_all(worklane.join("reviewing")).unwrap(); + + assert_eq!(tags(&temp), vec!["bug\t1"]); +}