Add a worklane completions command, and bump to 0.17.0

Every argument worklane takes names a ticket, a status, a shell or a skill, and
the shell offered a directory listing for all of them. `completions <shell>`
prints a script for fish, bash, zsh, elvish and powershell, following what frig
does, which is where the shape of this comes from.

Two halves, because neither alone is enough. `clap_complete` generates the
structure from the clap definition, so a flag added to `command.rs` is completed
without anyone touching `completions.rs`, and fish gets a hand-written block
appended for what only the board knows. That block runs `worklane ls --ids` in a
command substitution, one run per keypress, 2.5ms in release on a board of
seventy-five tickets.

A status is a `util::Status` value enum now rather than a string, which was the
plan's third step and pays for itself three ways. clap refuses an unknown one at
parse time naming the four, so `cmd_mv`'s `valid_statuses` and the status half of
`cmd_ls`'s error are gone and exit 2 is what an unreal status gets, the bargain
`--due` and `--priority` already take. `status_dirs()` and `DONE` are derived
from `Status::ALL`, so the flow is written once. And clap emits the four for `mv
--status` itself. Only half free: the fish generator emits nothing for the
possible values of a *positional*, so `ls <status>` and `completions <shell>` are
listed in the appended half after all, read off the enums with `possible_values`
rather than by hand.

`ls --ids` is the machine-readable listing, and prints the short id, a tab and
the title rather than the id alone. Both readers want both fields: fish takes
what follows a tab as the description, which is what makes `worklane show <TAB>`
a list of titles instead of hex, and a script takes the id back with `cut -f1`.
It includes done, where the decorated listing leaves done out, because a
completion has to be able to name a finished ticket and `show` is most often
pointed at one. It skips a missing status directory rather than refusing, since
an error printed over a shell prompt is worse than no candidates, and the
listing still refuses one so a person can act on it. The filters all still
apply, and an unknown `--campaign` is still refused ahead of everything.

Adding the mode tipped `cmd_ls` over the boundary AGENTS.md names, so it takes an
`LsArgs`, the way `add` took `AddArgs`.

More than the criteria asked, since the cost of each was a name in a list:
tickets are completed for `set`, `append`, `relate`, `check`, `uncheck`, the
second argument of `chown` and `assign`, and `relate`'s three target flags, plus
the skill names read off `install::SKILLS`. The three lists are kept honest by
tests that walk the clap definition and fail on a ticket-taking subcommand
missing from them, or listed at the wrong position. Nested subcommands are 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.

Position is counted rather than inferred. `__worklane_first_arg_of` reads
`$tokens[2]` and the token count instead of `__fish_seen_subcommand_from`,
because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish
has seen, and matching against the ticket list to find the position would run
worklane again inside the condition.

Files are turned off for the command and back on for `tui`, which is the one
argument that really is a path. The ticket said worklane takes no file arguments;
it takes those.

Campaigns and tags are completed nowhere, which needs a listing they do not have:
55ee6e3. And since fish runs whatever is on PATH, the completions are only as
current as the installed binary, an older one without `--ids` completing
nothing. That is in the README beside the install line.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-22 20:02:37 +02:00
co-authored by Claude Opus 5
parent 88918b2f8a
commit 373ba519b3
13 changed files with 816 additions and 70 deletions
+293
View File
@@ -0,0 +1,293 @@
//! 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 <status>` gets nothing. Same for `completions <shell>`. 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 <ticket>` and `assign "v1 release" <ticket>`, 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"];
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 = TICKET_FLAGS
.iter()
.map(|flag| format!("-l {flag}"))
.collect::<Vec<_>>()
.join(" ");
let statuses = possible_values(Status::value_variants());
let shells = possible_values(Shell::value_variants());
let skills = SKILLS
.iter()
.map(|skill| skill.name)
.collect::<Vec<_>>()
.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 <TAB>` 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 '__fish_seen_subcommand_from 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
# 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 {ticket_flags} -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
"#
)
}
/// 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<T: ValueEnum>(variants: &[T]) -> String {
variants
.iter()
.filter_map(|variant| variant.to_possible_value())
.map(|value| value.get_name().to_string())
.collect::<Vec<_>>()
.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 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.
#[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() {
Some(1) => assert!(
TICKET_COMMANDS.contains(&name),
"`worklane {name}` takes a ticket first but is not in TICKET_COMMANDS"
),
Some(2) => assert!(
TICKET_SECOND_COMMANDS.contains(&name),
"`worklane {name}` takes a ticket second but is not in \
TICKET_SECOND_COMMANDS"
),
index => panic!("`worklane {name}` takes a ticket at position {index:?}"),
}
}
}
}
#[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}");
}
}
/// 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<String> = 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 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' -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}"
);
}
}
}