`:mv --status ` offered the five statuses on the board and `:mv -s `
offered nothing: argument_at read the typed word with strip_prefix("--"),
so a word spelled with one hyphen was not a flag to it and fell through to
the positional arm, which counted a position that was not there.
long_name translates the letter through the command that holds the flag, so
the tables stay keyed on the long name and nothing here keeps a second list
of every option's letter. One letter, never a cluster: `mv -fs done` would
make the last letter the honest answer, 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.
The fish half had the same hole in its dynamic rules alone, which were
written as `-l <flag>`: `append -g <TAB>` offered nothing where
`append --tags <TAB>` offered the board's tags. fish_option reads the letter
off the definition per command, so an option given one tomorrow is offered
under it the day it is given. Clap's own generated rules already carried
both spellings, which is why a shell answered `mv -s ` and the board did
not.
a_short_flag_answers_what_its_long_spelling_answers walks every option with
both spellings on every command and nested command and pins that the two
answer the same, so this cannot come back one flag at a time.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
11 KiB
11 KiB
Shell Completions
The generated half, the fish half, and what keeps the two honest.
- Two halves, and the split is the point.
clap_completegenerates the structure from the clap definition, so a new flag or subcommand is completed without anyone touchingcompletions.rs. Only fish gets the second half, appended byfish_dynamic(), and it holds exactly what clap cannot know: the tickets on the board - The dynamic values come from worklane itself, as
worklane ls --idsin 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--idscompletes 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 <TAB>needs nothing here, and nothing for a positional, which is why thelsstatus and thecompletionsshell are listed in the fish half. Both lists are read off the enums withpossible_values, never written out, so a fifth status appears in the script on its own - Position is counted, not inferred. The four
__worklane_*predicates all read$tokens[2]and the token count rather than using__fish_seen_subcommand_from, becausecampaign lsandcampaign showare also anlsand ashowthat fish has seen, and because matching against the ticket list would run worklane again inside the condition.first_arg_ofandsecond_arg_ofcount a top-level command's arguments,nested_arg_ofmatches a parent and a child socampaign show <TAB>can be told fromchown alice <TAB>, which sit at the same token count, andcommand_isasks only which command this is, at any position in it - Every rule carrying
-lneeds a__worklane_command_is, andevery_rule_naming_an_option_is_scoped_to_a_commandis what enforces it. A barecomplete -c worklane -l tagdoes not just complete that option's values, it tells fish the whole tool accepts--tag:worklane init --<TAB>offered six options that onlyrelateandlshave. Fixed in 55ee6e3.__fish_seen_subcommand_from lsis not the scope to use, for the nesting reason above - The strongest completion check loads the script into fish and asks it for candidates.
fish_offers_the_commands_the_statuses_and_the_valuesintests/cmd_completions.rssources the generated script into a throwaway shell standing in a real board, with this build's directory on the front of PATH, and comparescomplete -Cagainst the ticket and the tag it put there. Every other test in the file reads the script as text, which cannot tell a rule that fires from one whose condition stopped matching, and that is how a completion actually breaks. Assert the values, not the flag names: clap emits every option's name on its own, so--tagsand--blocked-byare offered with every hand-written rule deleted; what the dynamic half adds is what comes after the flag. Two traps, both paid for once: the shell must havefish_complete_pathemptied, orcomplete -Cautoloads~/.config/fish/completions/worklane.fishand answers from whatever version wrote that, which is a guard that cannot fail; and the script is written beside the board rather than in it, since a rule that fires nothing falls back to listing the directory fish --no-executeis the floor under that, not an oracle. It catches a script that does not parse, quotes still open at the end of the file or an unclosed block. Measured, not assumed: an apostrophe interpolated into a-ddescription partway down re-balances against the next quote and parses, corrupting every rule in between while the check passes; the same apostrophe in the last rule reaches the end unbalanced and is caught. Only fish gets this, because only fish gets a hand-written half- The rule counts in the completion tests are hardcoded on purpose. The walkers go clap → list and never see an entry naming something that does not exist, so a bogus pair in
TAG_FLAGSis caught byevery_tag_rule_takes_the_annotation_as_its_descriptioncounting one rule too many. Deriving that number from the lists it checks would grow with the bogus entry and pass. Theseentotals in the walkers are hardcoded for the mirror reason, and both carry the note - The completion lists are kept honest by tests that walk the clap definition and fail on an argument left out of them.
TICKET_COMMANDSandTICKET_SECOND_COMMANDSby position,TICKET_FLAGS,CAMPAIGN_COMMANDS,CAMPAIGN_NESTED_COMMANDS,CAMPAIGN_FLAGSandTAG_FLAGSlikewise, the last against the test-localTAG_LIST_FLAGSandTAG_NEW_COMMANDSfor the tag arguments that deliberately get no rule. 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, the first argument ofcampaign showandcampaign set, andls --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 TICKET_FLAGSholds pairs, the command and the flag, and every ticket rule in the fish half is generated from it. Three commands carry a--clearand each takes something different:chown's names the ticket, since with no user to give there is no positional for it;relate's takes the kind and then the target;set's takes a field name clap already offers. So the command is half of the fact, and a list of bare flag names could only be scoped by hand, which is what thechown --clearrule used to be.every_ticket_flag_is_a_real_optionwalks each pair against the command it names, which a flat list could not do- The lists answer the board as well as the shell.
argument_atreads every one of them to say what the argument at a given index of a typed line names — a ticket, a campaign, a tag, or a fixed list it takes off clap — which is what the command prompt completes against, see tui-prompts.md. Position is counted there exactly as it is counted here, so the two cannot come to disagree aboutmv --status done <ticket>; a second table on the board would be a copy the tests above never read. The values are the one half that is not shared: fish runsworklane ls --idsand the board reads the rows the tab already holds TAG_FLAGSholds pairs where the others hold names, because the two options that take one tag are spelled differently:ls --tagfilters on one andappend --tagsadds them, so a single rule naming both would tell fish that each command accepts the other's flag. One rule per pair, generated infish_dynamic.add --tagsandset --tagsare in the test'sTAG_LIST_FLAGSinstead and get no rule: they take the whole list, so the token at the cursor isbug,tuiand fish replaces a token entire, which would throw away what is already typed. The test walks bothtagandtags, so the next one has to say which of the two it is- A
ValueEnumis never listed twice, andargument_atis why the fish half's two hand-written value lists are the only ones. clap emits the possible values of an option, somv --statusandset --clearneed nothing here and the board reads them off the same definition withArg::get_possible_values. Thelsstatus and thecompletionsshell 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 throughget_positionals, which needs noCommand::buildthe wayget_indexwould RELATION_KIND_FLAGSis the one position clap cannot answer for.relate --cleartakes 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 listsRelationKind::ALLand the table names the pairls --idsis 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 readscut -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--campaignis still refused- A flag is recognised by either spelling,
--statusand-salike.long_nametranslates 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 --statusoffered the five statuses andmv -soffered nothing. One letter, never a cluster —mv -fs donewould be the honest reading of the last letter, but--title,--acceptanceand a comment body all take a leading hyphen on purpose, and a criterion typed as-fixes the offsetmust not be answered with statuses.a_short_flag_answers_what_its_long_spelling_answerswalks 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 <TAB>offered nothing whereappend --tags <TAB>offered the board's tags, because the dynamic rules were rendered with-lalone.fish_optionreads 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_atresolves the group's child when the second word names one, socampaign ls --statereachesls's own arguments rather thancampaign's, which carry no such flag. Without that the prompt offered nothing where fish offered the three values, and the promise that aValueEnumadded anywhere is typeable on the board the day it is added held only for a top-level command campaign ls --idsis 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 candidatesworklane tagsis the third, and it is a command rather than a mode onls. Two reasons:ls --tag <tag>answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a--tagsbeside a--tagis one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, sobugandBuglist 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.mdused to tell the agent to count tags with ashowper ticket, and now points here