diff --git a/Cargo.lock b/Cargo.lock index 9daba37..7d3ff55 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1563,7 +1563,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.33.7" +version = "0.33.8" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 3347d75..ad9a250 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.33.7" +version = "0.33.8" edition = "2024" [dependencies] diff --git a/docs/completions.md b/docs/completions.md index 94aab1b..dd240c6 100644 --- a/docs/completions.md +++ b/docs/completions.md @@ -18,6 +18,8 @@ The generated half, the fish half, and what keeps the two honest. - **A `ValueEnum` is never listed twice, and `argument_at` is why the fish half's two hand-written value lists are the only ones.** clap emits the possible values of an *option*, so `mv --status` and `set --clear` need nothing here and the board reads them off the same definition with `Arg::get_possible_values`. The `ls` status and the `completions` shell are positionals, which the fish generator emits nothing for, so those two are written into the block from the enums — and the board reaches them through `get_positionals`, which needs no `Command::build` the way `get_index` would - **`RELATION_KIND_FLAGS` is the one position clap cannot answer for.** `relate --clear` takes a kind and then a target, two values of different kinds under one flag, so possible values on it would refuse every target. Both renderers therefore say so themselves: the fish rule lists `RelationKind::ALL` and the table names the pair - **`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 +- **A flag is recognised by either spelling, `--status` and `-s` alike.** `long_name` translates the letter through the command that holds the flag, so every table above stays keyed on the long name and nothing here keeps a second list of the letters. The prompt read a flag by its two hyphens until then: `mv --status ` offered the five statuses and `mv -s ` offered nothing. **One letter, never a cluster** — `mv -fs done` would be the honest reading of the last letter, but `--title`, `--acceptance` and a comment body all take a leading hyphen on purpose, and a criterion typed as `-fixes the offset` must not be answered with statuses. `a_short_flag_answers_what_its_long_spelling_answers` walks every option with both spellings on every command and nested command, so an option given a letter tomorrow is covered the day it is given one +- **The fish rules name the letter too, `-s g -l tags`.** The same hole on the other half: `append -g ` offered nothing where `append --tags ` offered the board's tags, because the dynamic rules were rendered with `-l` alone. `fish_option` reads the letter off the definition per command, so a rule for an option with none is what it always was. Clap's own generated half already emitted both spellings, which is why only the dynamic rules were short - **A flag's possible values are read off the command that *holds* the flag, nested or not.** `argument_at` resolves the group's child when the second word names one, so `campaign ls --state` reaches `ls`'s own arguments rather than `campaign`'s, which carry no such flag. Without that the prompt offered nothing where fish offered the three values, and the promise that a `ValueEnum` added anywhere is typeable on the board the day it is added held only for a top-level command - **`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 diff --git a/src/completions.rs b/src/completions.rs index 259bbad..bf953d2 100644 --- a/src/completions.rs +++ b/src/completions.rs @@ -111,6 +111,36 @@ pub const TAG_NESTED_COMMANDS: [(&str, &str); 1] = [("tags", "set")]; /// every target. pub const RELATION_KIND_FLAGS: [(&str, &str); 1] = [("relate", "clear")]; +/// The long name of the flag a typed word spells, or nothing where it is not a flag. +/// +/// `--status` is its own name and `-s` is clap's to translate, off the command that holds +/// the flag: a table of the shorts kept here would be a second list of every option the +/// tool has, and it would go wrong the first time one was given a letter. +/// +/// **One letter, never a cluster.** `mv -fs done` is force and status and it is `status` +/// that takes the word after it, so the last letter of a cluster would be the honest +/// answer — but `--title`, `--description`, `--acceptance`, `--plan` and a comment body all +/// take a leading hyphen on purpose, and reading `-fixes the offset` as a cluster would +/// offer statuses inside a criterion. A clustered short is rare on a board where the line +/// is typed a word at a time; a hyphen-leading prose value is a documented feature. +fn long_name(arg: &str, holder: Option<&clap::Command>) -> Option { + if let Some(long) = arg.strip_prefix("--") { + return (!long.is_empty()).then(|| long.to_string()); + } + + let mut letters = arg.strip_prefix('-')?.chars(); + let short = match (letters.next(), letters.next()) { + (Some(letter), None) => letter, + _ => return None, + }; + + holder? + .get_arguments() + .find(|option| option.get_short() == Some(short)) + .and_then(|option| option.get_long()) + .map(str::to_string) +} + /// What an argument of a typed line names, where worklane can answer what goes there. /// /// The board's command prompt completes against this: the tables above say *what* the @@ -178,8 +208,10 @@ pub fn argument_at(args: &[String], index: usize) -> Option { .or(group); // A flag's value is the argument after it, which is where the flag sits whether the - // value is half typed or has not been started. - if let Some(flag) = args.get(index - 1).and_then(|arg| arg.strip_prefix("--")) { + // value is half typed or has not been started. Spelled long or short: `-s` is the same + // flag as `--status` and the row has to answer both, which is what `long_name` is for. + if let Some(flag) = args.get(index - 1).and_then(|arg| long_name(arg, holder)) { + let flag = flag.as_str(); if TICKET_FLAGS.contains(&(verb, flag)) { return Some(Argument::Ticket); } @@ -281,8 +313,9 @@ fn fish_dynamic() -> String { let ticket_flags = TICKET_FLAGS .iter() .map(|(command, flag)| { + let option = fish_option(command, flag); format!( - "complete -c worklane -n '__worklane_command_is {command}' -l {flag} \\\n \ + "complete -c worklane -n '__worklane_command_is {command}' {option} \\\n \ -x -a '(worklane ls --ids)'" ) }) @@ -299,12 +332,13 @@ fn fish_dynamic() -> String { .map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}")) .collect::>() .join("; or "); - let campaign_flags = flag_list(&CAMPAIGN_FLAGS); + let campaign_flags = flag_list("ls", &CAMPAIGN_FLAGS); let tag_flags = TAG_FLAGS .iter() .map(|(command, flag)| { + let option = fish_option(command, flag); format!( - "complete -c worklane -n '__worklane_command_is {command}' -l {flag} \\\n \ + "complete -c worklane -n '__worklane_command_is {command}' {option} \\\n \ -x -a '(worklane tags | cut -f1,3)'" ) }) @@ -442,15 +476,40 @@ 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 { +/// Option names as fish wants them on a `complete` line, `-s o -l one -l two`, for the +/// options of one command. +fn flag_list(command: &str, flags: &[&str]) -> String { flags .iter() - .map(|flag| format!("-l {flag}")) + .map(|flag| fish_option(command, flag)) .collect::>() .join(" ") } +/// One option as fish names it: its long name, and its letter where clap gave it one. +/// +/// `-s g -l tags` rather than `-l tags` alone, or `append -g ` offers nothing where +/// `append --tags ` offers the board's tags — the same hole the board's own prompt had +/// until `long_name`, and the reason one table answers both halves is that neither may +/// answer a spelling the other does not. The letter is read off the definition and never +/// written here, so an option given one tomorrow is offered under it the day it is given. +fn fish_option(command: &str, flag: &str) -> String { + let cli = crate::command::Cli::command(); + let short = cli + .find_subcommand(command) + .and_then(|command| { + command + .get_arguments() + .find(|option| option.get_long() == Some(flag)) + }) + .and_then(|option| option.get_short()); + + match short { + Some(letter) => format!("-s {letter} -l {flag}"), + None => format!("-l {flag}"), + } +} + /// 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 @@ -774,6 +833,87 @@ mod tests { assert!(shells.contains(&"fish".to_string()), "{shells:?}"); } + /// The fish half names an option by its letter too, wherever clap gave it one, so a + /// dynamic rule answers both spellings the way the prompt does. + #[test] + fn a_fish_rule_names_the_option_by_its_letter_as_well() { + let script = fish_dynamic(); + + // `append --tags` is the one flag in these tables with a letter, and it is the + // whole reason the rule is rendered rather than written: `-g` offered nothing. + assert!( + script.contains("-s g -l tags"), + "the tags rule does not name its letter:\n{script}" + ); + + // And one without stays as it was, rather than gaining an empty `-s`. + assert!(script.contains("-l campaign"), "{script}"); + assert!(!script.contains("-s "), "an option with no letter got one:\n{script}"); + + // Read off the definition, never written here. + assert_eq!(fish_option("append", "tags"), "-s g -l tags"); + assert_eq!(fish_option("ls", "tag"), "-l tag"); + assert_eq!(fish_option("ls", "nosuchflag"), "-l nosuchflag"); + } + + /// A flag spelled short answers exactly what the same flag spelled long answers, on + /// every command and every option that has both. + /// + /// Walked off the clap definition rather than listed, so an option given a letter + /// tomorrow is covered the day it is given one. `-s` was the report: `mv --status ` + /// offered the five statuses and `mv -s ` offered nothing, because the row read a flag + /// by its two hyphens. A boolean's two spellings agree as well, both answering nothing, + /// which is the same statement about a value that is not there. + #[test] + fn a_short_flag_answers_what_its_long_spelling_answers() { + let cli = crate::command::Cli::command(); + let mut seen = 0; + + for command in cli.get_subcommands() { + let children: Vec<(String, &clap::Command)> = command + .get_subcommands() + .map(|child| (format!("{} {}", command.get_name(), child.get_name()), child)) + .collect(); + + for (line, holder) in + std::iter::once((command.get_name().to_string(), command)).chain(children) + { + for option in holder.get_arguments() { + let (Some(short), Some(long)) = (option.get_short(), option.get_long()) else { + continue; + }; + + seen += 1; + assert_eq!( + at_cursor(&format!("{line} -{short} ")), + at_cursor(&format!("{line} --{long} ")), + "`-{short}` and `--{long}` answer differently on `{line}`" + ); + } + } + } + + assert!(seen > 20, "only {seen} options had both spellings, which is too few"); + } + + /// The two the report named, spelled out, so the walk above cannot pass by finding + /// nothing on either spelling. + #[test] + fn a_short_flag_reaches_the_values_and_the_board() { + let listed: Vec = Status::ALL.iter().map(|s| s.as_str().to_string()).collect(); + assert_eq!(values("mv -s "), Some(listed), "`-s` offers no statuses"); + assert_eq!(values("mv -s bac"), values("mv --status bac"), "half typed"); + + // A tag, which comes off the board rather than out of the enum. + assert_eq!(at_cursor("append -g "), Some(Argument::Tag { declared: false })); + + // And a cluster is deliberately not read, because `--title`, `--acceptance` and a + // comment body all take a leading hyphen: a value spelled `-fixes the offset` must + // not be read as `-s` and answered with statuses. + assert_eq!(at_cursor("mv -fs "), None); + assert_eq!(at_cursor("comment 1b78a24 -fs "), None); + } + /// The flag on a nested command is answered the same way, from the enum: nothing here /// knows what a campaign's states are, and the values reach the prompt and fish alike /// the day a fourth one is added to `CampaignState`.