//! Shell completions. //! //! Two halves, because neither alone is enough. //! //! `clap_complete` generates the structure (subcommands, flags, their arguments) //! straight from the clap definition, so a new flag never needs remembering here. But it //! can only offer values it knows at compile time, and the value worth completing for //! worklane is the ticket, which lives in the board the command is run above. //! //! So the fish output gets a hand-written block appended that asks worklane itself. That //! costs one `worklane ls --ids` per keypress, which measured at 2.5ms in release on a //! board of seventy-five tickets, comfortably below anything a person notices. //! //! The four statuses are half clap's: `Status` is a `ValueEnum`, so it emits them for //! `mv --status`, but the fish generator does not emit possible values for a *positional* //! and `ls ` gets nothing. Same for `completions `. So the block below //! lists those two, from the enums rather than by hand. use std::io; use clap::{CommandFactory, ValueEnum}; use clap_complete::Shell; use crate::install::SKILLS; use crate::util::Status; /// Subcommands whose first positional is a ticket. /// /// Kept honest by a test rather than by memory: a new ticket-taking subcommand that is /// missing here silently loses completion, which nothing else would catch. pub const TICKET_COMMANDS: [&str; 8] = [ "show", "mv", "comment", "set", "append", "relate", "check", "uncheck", ]; /// Subcommands whose *second* positional is the ticket, because they name two things. /// /// `chown alice ` and `assign "v1 release" `, which put the ticket /// second deliberately, see AGENTS.md. The first argument of each is a user or a /// campaign, and neither is completed. 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`, `campaign set` and `campaign append`, and they are why the fish half /// needs a third position helper: their 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); 3] = [ ("campaign", "show"), ("campaign", "set"), ("campaign", "append"), ]; /// 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"]; /// 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); if shell == Shell::Fish { write!(out, "{}", fish_dynamic())?; } Ok(()) } /// The dynamic half, appended to what clap generated. /// /// Fish merges completions from every `complete` call, so these add to the generated /// rules rather than replacing them. fn fish_dynamic() -> String { let ticket_commands = TICKET_COMMANDS.join(" "); let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" "); let ticket_flags = flag_list(&TICKET_FLAGS); let campaign_commands = CAMPAIGN_COMMANDS.join(" "); let campaign_nested = CAMPAIGN_NESTED_COMMANDS .iter() .map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}")) .collect::>() .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 .iter() .map(|skill| skill.name) .collect::>() .join(" "); format!( r#" # --------------------------------------------------------------------------- # Dynamic values, appended by `worklane completions fish`. Fish accumulates # completions, so these add to the generated rules above. # --------------------------------------------------------------------------- # Almost every argument worklane takes names something on the board rather than # something on disk, so stop fish falling back to the directory listing. Without this, # `worklane show 1b78a24 ` offers Cargo.toml and src/. 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 '__worklane_command_is tui' \ -a '(__fish_complete_directories)' -d project # Position is counted rather than inferred from what has been typed: matching against # the ticket list would run worklane again inside the condition, and would also keep # offering tickets after one had been chosen. # # The subcommand is the second token, so its first argument is being typed once two # tokens are there. `$tokens[2]` rather than `__fish_seen_subcommand_from`, because # `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, # and their arguments are not what these complete. function __worklane_first_arg_of set -l tokens (commandline -opc) test (count $tokens) -eq 2; and contains -- $tokens[2] $argv end function __worklane_second_arg_of set -l tokens (commandline -opc) 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 \ -n '__worklane_first_arg_of {ticket_commands}; or __worklane_second_arg_of {ticket_second_commands}' \ -a '(worklane ls --ids)' # `relate` takes its targets as option values, so they are completed by flag rather # than by position. 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. Three fields now, the tag, its count and its annotation, and fish takes everything # after the *first* tab as one description, so the count is dropped here rather than landing # in the middle of the prose. `cut` and not `string replace` because the columns are what is # being picked, and `cut -f1` is how a script reads this listing anyway. # # What is left is the annotation, and a tag the board carries but has never declared has # none: it is offered with no description at all, which is the near-duplicate the file was # added to catch. The count used to be the description and said the same thing more weakly. complete -c worklane -n '__worklane_command_is ls' {tag_flags} \ -x -a '(worklane tags | cut -f1,3)' # 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 | cut -f1,3)' # `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 '__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 # positional needs them listed, and the same goes for the shell below. complete -c worklane -n '__worklane_first_arg_of ls' -a '{statuses}' -d status complete -c worklane -n '__worklane_first_arg_of completions' -a '{shells}' -d shell # Shipped with the binary, so this list comes from `install::SKILLS` and cannot fall # behind it. complete -c worklane -n '__worklane_first_arg_of install-skill' -a '{skills}' -d skill "# ) } /// 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 /// is offered without anybody remembering this file. A variant marked hidden is left out, /// which is what `to_possible_value` returning `None` means. fn possible_values(variants: &[T]) -> String { variants .iter() .filter_map(|variant| variant.to_possible_value()) .map(|value| value.get_name().to_string()) .collect::>() .join(" ") } #[cfg(test)] mod tests { use super::*; /// Built, not just derived: an index is assigned when the command is built, and the /// positionals of an unbuilt one all report `None`. fn command() -> clap::Command { let mut cli = crate::command::Cli::command(); cli.build(); 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. /// /// 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 (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(&top), "`worklane {name}` takes a ticket first but is not in TICKET_COMMANDS" ), Some(2) => assert!( TICKET_SECOND_COMMANDS.contains(&top), "`worklane {name}` takes a ticket second but is not in \ TICKET_SECOND_COMMANDS" ), index => panic!("`worklane {name}` takes a ticket at position {index:?}"), } } } } /// 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, 5, "expected assign, campaign show, campaign set, campaign append and ls --campaign" ); } /// Commands whose tag positional names a tag that does not exist yet. /// /// `tags add` declares a word the board has never carried, so completing it from /// `worklane tags` would offer exactly the values the command refuses. Recorded rather /// than skipped, so the *next* tag positional has to say which it is: `tags set` takes /// a tag that is already declared and wants a rule in the fish block, and the test /// below fails until it gets one or lands here. /// /// In the test module because nothing outside it reads the list; the rule it encodes is /// about what the fish block is missing, which is a test's question. const TAG_NEW_COMMANDS: [(&str, &str); 1] = [("tags", "add")]; /// 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 Some(long) = arg.get_long() else { let known = match path.as_slice() { [parent, child] => { let pair = (parent.as_str(), child.as_str()); TAG_NESTED_COMMANDS.contains(&pair) || TAG_NEW_COMMANDS.contains(&pair) } _ => false, }; assert!( 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; }; assert!( TAG_FLAGS.contains(&long), "`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS" ); } 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 /// `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(); let known: Vec<&str> = cli.get_subcommands().map(|c| c.get_name()).collect(); for name in TICKET_COMMANDS.iter().chain(TICKET_SECOND_COMMANDS.iter()) { assert!(known.contains(name), "no such subcommand: {name}"); } } /// `chown --clear` takes a ticket, so it is completed like one, and only under /// `chown`: `set --clear` is the same flag name carrying a field. #[test] fn chowns_clear_is_completed_with_tickets_and_sets_is_not() { let script = fish_dynamic(); let rule = script .lines() .find(|line| line.starts_with("complete") && line.contains("-l clear")) .expect("chown --clear has a rule of its own"); 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!( chown.get_arguments().any(|arg| arg.get_long() == Some("clear")), "`chown` has no --clear for the rule to complete" ); assert!( !TICKET_FLAGS.contains(&"clear"), "--clear in TICKET_FLAGS would offer tickets to `set --clear`, which takes a field" ); } /// The flags completed as tickets have to be `relate`'s actual flags, or the rule /// completes an option nothing accepts. #[test] fn every_ticket_flag_is_a_real_option() { let relate = command() .find_subcommand("relate") .expect("relate exists") .clone(); let known: Vec = relate .get_arguments() .filter_map(|arg| arg.get_long().map(str::to_string)) .collect(); for flag in TICKET_FLAGS { assert!(known.contains(&flag.to_string()), "`relate` has no --{flag}"); } } #[test] fn the_fish_script_asks_worklane_for_its_tickets() { let script = fish_dynamic(); assert!(script.contains("worklane ls --ids")); // Both positions, in one rule. assert!(script.contains("__worklane_first_arg_of show")); assert!(script.contains("__worklane_second_arg_of chown assign")); // Nothing here takes a file, bar the one that does. assert!(script.contains("complete -c worklane -f\n")); assert!(script.contains("__fish_complete_directories")); // Generated from `install::SKILLS`, so every shipped skill is in it. 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}"); } /// Every rule that reads the tag listing drops the count, because `worklane tags` prints /// three fields and fish takes everything after the first tab as the description. Left /// whole, a tag would be described as its count, a tab and its annotation. /// /// Pinned per rule rather than once over the script: a rule added later that reads /// `worklane tags` raw is the bug this catches, and it would not show up in a single /// `contains`. #[test] fn every_tag_rule_takes_the_annotation_as_its_description() { let script = fish_dynamic(); let reading: Vec<&str> = script .lines() .filter(|line| line.contains("(worklane tags")) .collect(); assert_eq!( reading.len(), 2, "expected the ls --tag rule and the tags set one: {reading:?}" ); for line in reading { assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}"); } } /// 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. #[test] fn the_fish_script_lists_the_statuses_and_the_shells() { let script = fish_dynamic(); for status in Status::ALL { assert!( script.contains(status.as_str()), "the ls positional is never offered {}", status.as_str() ); } assert!(script.contains("-a 'backlog committed reviewing done discarded' -d status")); for shell in ["fish", "bash", "zsh", "elvish", "powershell"] { assert!(script.contains(shell), "the shell positional is never offered {shell}"); } } /// The four for `mv --status` are clap's, which is half of why `Status` is a /// `ValueEnum`. If clap ever stops emitting them, the fish half has to carry them /// too, and this is what says so. #[test] fn clap_emits_the_statuses_for_the_status_flag() { let mut out = Vec::new(); generate(Shell::Fish, &mut out).expect("generates"); let script = String::from_utf8(out).expect("utf8"); let flag = script .lines() .find(|line| line.contains("using_subcommand mv") && line.contains("-l status")) .expect("mv --status has a rule of its own"); assert!(flag.contains("backlog"), "{flag}"); } #[test] fn generating_fish_produces_both_halves() { let mut out = Vec::new(); generate(Shell::Fish, &mut out).expect("generates"); let script = String::from_utf8(out).expect("utf8"); // clap's half. assert!(script.contains("complete -c worklane")); assert!(script.contains("install-skill")); // Ours. assert!(script.contains("__worklane_first_arg_of")); } #[test] fn other_shells_get_only_the_generated_half() { for shell in [Shell::Bash, Shell::Zsh] { let mut out = Vec::new(); generate(shell, &mut out).expect("generates"); let script = String::from_utf8(out).expect("utf8"); assert!( !script.contains("__worklane_first_arg_of"), "fish-only helpers leaked into {shell}" ); } } }