campaign ls printed every campaign and offered no way to narrow it, and the row was assembled by hand, so a long title pushed the standing out of line with the row above it and the created date the file already carries was not shown at all. --state takes open, done or empty and matches against Standing::state(), so the derived value keeps one definition: a campaign reads [open] in the listing if and only if --state open lists it. --state rather than --status, which names one of the five ticket statuses everywhere else and would invite --state backlog here. empty is the third value because an empty campaign derives None deliberately, and a filter that could not reach those would leave what has been filed and forgotten answerable only by reading the whole listing. A filter that matches nothing names the value back, since a silent listing reads as the other empty case. The filter reaches --ids as well, the way ls --ids keeps its own, and is the only thing that makes that path count members: an unfiltered completion is as cheap as it was. The columns are measured on the raw values and padded before anything is painted, the rule metadata_cells follows. The codename is measured with the title rather than given a column of its own: a campaign filed without one spends nothing on it, so a column for it would be one most rows pad into and some leave empty, and what a reader lines up is where a name ends and its progress begins. A flag's possible values now come off the command that holds the flag, so campaign ls --state reaches ls's own arguments rather than campaign's. The prompt offered nothing there while fish offered the three values, which made a liar of the rule that a ValueEnum added anywhere is typeable on the board the day it is added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
25 lines
10 KiB
Markdown
25 lines
10 KiB
Markdown
# Shell Completions
|
|
|
|
The generated half, the fish half, and what keeps the two honest.
|
|
|
|
- **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 <TAB>` 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.** 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 <TAB>` can be told from `chown alice <TAB>`, 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 --<TAB>` 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 strongest completion check loads the script into fish and asks it for candidates.** `fish_offers_the_commands_the_statuses_and_the_values` in `tests/cmd_completions.rs` sources the generated script into a throwaway shell standing in a real board, with this build's directory on the front of PATH, and compares `complete -C` against 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 `--tags` and `--blocked-by` are 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 have `fish_complete_path` emptied, or `complete -C` autoloads `~/.config/fish/completions/worklane.fish` and 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-execute` is 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 `-d` description 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_FLAGS` is caught by `every_tag_rule_takes_the_annotation_as_its_description` counting one rule too many. Deriving that number from the lists it checks would grow with the bogus entry and pass. The `seen` totals 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_COMMANDS` and `TICKET_SECOND_COMMANDS` by position, `TICKET_FLAGS`, `CAMPAIGN_COMMANDS`, `CAMPAIGN_NESTED_COMMANDS`, `CAMPAIGN_FLAGS` and `TAG_FLAGS` likewise, the last against the test-local `TAG_LIST_FLAGS` and `TAG_NEW_COMMANDS` for 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 of `campaign show` and `campaign set`, 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
|
|
- **`TICKET_FLAGS` holds pairs, the command and the flag, and every ticket rule in the fish half is generated from it.** Three commands carry a `--clear` and 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 the `chown --clear` rule used to be. `every_ticket_flag_is_a_real_option` walks 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_at` reads 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](tui-prompts.md). Position is counted there exactly as it is counted here, so the two cannot come to disagree about `mv --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 runs `worklane ls --ids` and the board reads the rows the tab already holds
|
|
- **`TAG_FLAGS` holds pairs where the others hold names**, because the two options that take one tag are spelled differently: `ls --tag` filters on one and `append --tags` adds them, so a single rule naming both would tell fish that each command accepts the other's flag. One rule per pair, generated in `fish_dynamic`. `add --tags` and `set --tags` are in the test's `TAG_LIST_FLAGS` instead and get no rule: they take the *whole* list, so the token at the cursor is `bug,tui` and fish replaces a token entire, which would throw away what is already typed. The test walks both `tag` and `tags`, so the next one has to say which of the two it is
|
|
- **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'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 <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
|
|
|