Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
cd7c99fe39 | ||
|
|
b63b60eefc | ||
|
|
7470255a22 | ||
|
|
b4534eb86d | ||
|
|
96cddc14ad | ||
|
|
f16e2aba0c |
@@ -1,7 +1,7 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Project Structure
|
||||
- `src/main.rs` - dispatch, the SIGPIPE reset, and the TUI event loop
|
||||
- `src/main.rs` - `dispatch`, the one mapping from a parsed command to its handler, the SIGPIPE reset, and the TUI event loop
|
||||
- `src/command.rs` - CLI argument definitions using clap derive
|
||||
- `src/completions.rs` - the generated completion script and the fish half that asks the board
|
||||
- `src/handlers.rs` - one `cmd_*` per subcommand
|
||||
@@ -53,7 +53,8 @@ repo. Do not restate any of it in this file: a second copy is a copy that goes s
|
||||
and this file is for what someone changing worklane's own code needs.
|
||||
|
||||
## Testing
|
||||
- Run: `cargo test`
|
||||
- **Run `make check` before committing**: `cargo fmt --check`, then `cargo clippy --all-targets -- -D warnings`, then `cargo test`, cheapest first. That is the whole of the enforcement, and it is deliberate rather than a stopgap: this repo has no CI and does not want any, and a git hook is a per-clone opt-in the way `blame.ignoreRevsFile` is, so neither can be relied on. What was missing was one name to type, so the two rules below are a command and not a memory. `-D warnings` is what makes clippy's opinion an exit code; a warning printed into a wall of cargo output is unread, not clean. The completion checks are inside `cargo test` rather than a target of their own, since a second thing to remember is the problem this solves
|
||||
- Run one suite: `cargo test`
|
||||
- Tests use `assert_cmd` and `assert_fs` for CLI testing
|
||||
- `setup_worklane()` creates temp `.worklane/` with the four flow status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it. **The fixtures deliberately do not create `discarded/`**, so every discard test runs against a board that predates the status and `mv_creates_the_discarded_directory_on_a_board_that_predates_it` is not the only thing exercising the on-demand creation
|
||||
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
|
||||
@@ -62,8 +63,8 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **`WORKLANE_KEEP_FIXTURES=1 cargo test` keeps the fixtures and prints each path.** Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, and `Fixture::swept()` turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment
|
||||
- **Verify a claim about leaked fixtures against a clean temp dir, not against `/tmp`.** `TMPDIR=/tmp/scratch cargo test` then count what is left in it: `/tmp` still holds the historical leak, so counting there measures the past rather than the change
|
||||
- In `tui.rs`, `write_member_card` is `write_tagged_card` plus a Campaign field and `write_campaign` puts a campaign on disk, creating the campaigns directory as it goes — `board_dir()` deliberately does not, so every test that does not write one is also the test that a board with no campaigns draws. `picker_rows` cuts the picker's list out of the frame by its own geometry, for the reason `overlay_title_row` exists: a card carries the same campaign label, so a search over every row finds the board rather than the list
|
||||
- **`cargo clippy --all-targets` is clean. Keep it clean**, and do not silence a lint that is pointing at something real. The only two `allow`s in the tree sit on the `create_ticket` fixtures in `cmd_mv.rs` and `cmd_show.rs`, each carrying the reason and what would replace it
|
||||
- **`cargo fmt --check` is clean too, and `rustfmt.toml` is what makes that affordable.** rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:
|
||||
- **`cargo clippy --all-targets` is clean, and `make check` is what says so. Keep it clean**, and do not silence a lint that is pointing at something real. The only two `allow`s in the tree sit on the `create_ticket` fixtures in `cmd_mv.rs` and `cmd_show.rs`, each carrying the reason and what would replace it
|
||||
- **`cargo fmt --check` is clean too, `make check` runs it first, and `rustfmt.toml` is what makes that affordable.** rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:
|
||||
|
||||
| setting | value | why |
|
||||
|---|---|---|
|
||||
@@ -96,7 +97,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
|
||||
- An empty `--due` keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
|
||||
- **`campaign add --codename` is validated at parse time by `codename`**, which is `non_empty` plus one word. The board draws it as a label with a mark and no quoting, so `~beaver release` on that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reason `ls --tag` refuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold
|
||||
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser
|
||||
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser. **`append --tags` is the one place the field has an empty form and the argument still takes `non_empty`**: `append` has no `--clear` of its own, so naming one would send the caller looking on this command for a flag that is `set`'s
|
||||
- **A status is a `util::Status`, not a string.** `mv --status` and the `ls` positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain `--due` and `--priority` take, and it is what lets the shells complete the four for free. `Status::ALL` is the flow order, which `status_dirs()` and `cmd_mv` both read rather than spelling the names again, and `DONE` is defined from it
|
||||
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
|
||||
- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
|
||||
@@ -111,8 +112,12 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **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 five 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 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
|
||||
- **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 five 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
|
||||
- **`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
|
||||
- **`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
|
||||
- **`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
|
||||
@@ -351,6 +356,35 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Both closed footers name `/`, since the jump works with a ticket open as well: it moves the selection and the overlay follows
|
||||
- Out of scope on purpose, each its own ticket once the input mode exists: `n` and `N` for the next and previous match, searching the description, tags or owner, regex, and filtering the board down to matches rather than selecting one
|
||||
|
||||
### The Command Prompt
|
||||
- **`prompt: Option<Prompt>` is the whole mode**, the shape `search` and `detail` use: open and content cannot disagree, and closing it leaves nothing to reset. `Prompt` carries the line, the cursor as a byte offset into it, and `refused`, which is `Search::missed` with something to say
|
||||
- **`Board::prompt_key` is third in the pre-dispatch**, beside `search_key` and `picker_key` and on the same contract: while a command is being typed `q` is a letter, `d` leaves the columns alone and `tab` stays out of the project tabs, and `ctrl-c` is the one key declined. It takes a `Size` for enter's sake: running a command reloads the board and then has to bring the ticket it moved back into view, which is the measurement `follow_selection` takes. Only one of the two prompts can be open at once: `:` is reachable from the action arms alone, and while either has the keyboard the other's key is a character in a line
|
||||
- **`esc` and `enter` are the mode's own keys and are answered in `prompt_key`; everything else belongs to the line and goes to `Prompt::key`.** That is also what keeps the borrow straight, since closing the prompt takes the whole board and editing takes only the prompt. Left, right, home, end, backspace and `ctrl-w` behave as they do in a shell, and `ctrl-w` eats the separators behind the cursor before the word behind those, so one press at the end of `mv 1b78a24 ` takes the id. There is deliberately no `tab`: suggesting the selected ticket is 00a14e7, and until then it is a key that must not reach the tabs
|
||||
- **The grammar is clap's, with nothing restated.** The line is tokenised by `split_line`, the binary's own name goes in front, and the arguments go to the same `Cli` definition the shell reaches, so a flag added to a command is typeable here the day it is added. Through `Cli::command().try_get_matches_from_mut` rather than `try_parse_from`, for what the matches give back: `command_name` walks the subcommands to name what resolved (`campaign show`, not `campaign`) instead of a `match` over every variant, which would be a second list of every verb the CLI has and one that goes stale silently
|
||||
- **`refused` is cleared by an edit and not by a movement.** The message is about the line, and moving the cursor does not change the line. `Prompt::key` clears it in the three arms that write to the line
|
||||
- **A line that ends inside a quote never reaches clap.** That is what `Unclosed` is for: a grammar complaint about a sentence nobody finished describes the wrong thing. Enter on an empty line, or one of nothing but separators, closes the prompt with nothing said, the way `esc` does — the bare form of the CLI opens a board and there is one on the screen
|
||||
- **Enter runs it, through `main.rs`'s `dispatch` and never through a handler this file names.** That match is the one mapping from a parsed command to the function that performs it: `main` calls it with its own stdout and the working directory, `Board::run` calls it with a buffer and the selected tab's root. A second copy inside `tui.rs` would drift the first time a command was added, and it would drift *silently*, since both halves go on compiling. The match is exhaustive so a new verb cannot fall into an `_` arm and do nothing, and `main_and_the_prompt_run_one_dispatch_table` reads both files as text to pin it. Only `tui` is matched outside the table, in `main`, because the board is that table's caller rather than an entry in it; reached from the prompt it is refused in those words
|
||||
- **`from_arg_matches` on the same matches gives `run` the typed values.** One parse, two readings: `command_name` walks the subcommands to name what resolved and `from_arg_matches` reconstructs the `Cli`. A `match` over every `Command` variant to get one or the other would be a second list of every verb the CLI has
|
||||
- **The handler's own words are what the board reports, word for word.** Those messages are written for a person already, and a second set kept here would go stale the first time one of them changed. The sink is a buffer, so the words come back as text and the board styles them; it is plain for the same reason `Detail` holds spans, since a ratatui paragraph prints an escape rather than obeying it. An error never goes through a sink at all — `color_text` asks the *process* about its stdout, which under the board answers yes about a terminal the message is not going to — so `error_lines` runs `without_escapes` over it and puts each cause on a line of its own
|
||||
- **A handler that errors leaves the prompt open with the line intact.** The usual cause is an ambiguous id, and the fix is two more characters rather than the whole line retyped from `:`. Ambiguity is an `Err` carrying the candidates, not a print and an `exit`, which is what makes it safe to reach from here at all
|
||||
- **The reload after a command is unconditional, and runs whether it failed or not.** `tick` reloads on the digest, which is right for a change made in another pane and needless latency for one the board just made: the reader would watch their own `mv` take up to a poll interval to appear. Either way, because a handler that failed part way through has still written
|
||||
- **The selection is restored by uuid across that reload, never by index.** `mv` puts the card in another column, `set --title` renames its file, and a filter can drop it out of view entirely, so the slot is not the ticket. `Board::reselect` has three answers: the card is in a drawn column and the selection goes to it; it is on the board but in a column the rotation is hiding, which is where `--status done` lands by default, so the notice says where it went and which key shows it; or the filter no longer holds it, which is said too, since a card vanishing from under the highlight reads as a bug in the board
|
||||
- **The merge tab is refused, for now.** It is the one tab that is not a board — its cards came from several `.worklane` directories and it is none of them — so `Board::current_project` answers `None` there and the command is refused rather than landing on whichever project came first. Routing by the card a command names is ebc5755. The project is resolved by index and not by the tab's name, which is a label two projects can share: e1d79c3 is exactly that, and a write routed by name would be that bug with a file changing at the end of it
|
||||
- **`Notice` holds as many lines as the command used, and `Board::notice_on_row` decides where they go.** One line with nothing else holding the row draws on the footer, where a copy's notice has always drawn. Anything else — several lines, or any answer at all while the prompt is still open on an error — draws as a box at the foot of the columns, cut to what the columns leave with the dropped count on its last row. A box rather than more rows of footer, and that is the whole reason it is an overlay: a footer that grew and shrank as notices came and went would reflow the columns on every keypress, moving every card the reader is looking at. `draw` and `draw_footer` both ask `notice_on_row`, so the two cannot come to disagree and draw the message twice or not at all
|
||||
- **What a refused line shows is clap's own message with the usage block cut off**, which is also what drops the `--help` line after it. `--help` is the exception: it parses as an error of the kind that means *print this* and what it would print is a page, so it is caught and answered in a row's worth of words, or clap's help lands on the alternate screen the way an unsunk `println!` would. `--version` goes through the ordinary path, because what it prints is one line by construction. `ColorChoice::Never` on the command, so nothing that reaches the row carries an escape
|
||||
- **The keys' width comes off the row before the line is windowed**, so a long command does not push them off the end; a message takes the row from the keys instead, since the reader has just been told something and `esc` and `enter` still do what they did. `prompt_window` anchors the window on the cursor's right edge, which costs the text *after* the cursor on a long line: keeping both ends needs a scroll offset in state, and the draw is where the width is known and the state is not writable
|
||||
- `: command` is named in every footer state, because the key works in every one of them, and the prompt's own key is drawn as `↵ run`
|
||||
|
||||
### The Prompt's Recall
|
||||
- **`up` and `down` walk the lines already typed, and the lines are on disk.** `.wlhistory` in the board's own folder, appended as each line is entered. It is the one file under `.worklane` the board writes rather than a command, and the only one that is not markdown, which is the cost of a recall worth having: a board is opened and closed all day, and one that emptied on quit would only help inside a single sitting
|
||||
- **`Recall` is per tab, parallel to `Board::tabs`**, so the tab in view decides which list `up` walks. A project's lines are the ones naming its ticket ids, and handing another board's `mv` back on this one would offer an id that resolves to nothing there. The tabs are fixed for the run, so the two vectors cannot drift, and the same index that picks the tab picks the recall
|
||||
- **The merge tab has no file.** It is the one tab that is not a board, `current_project` answers `None` there and a command typed there is refused for that reason, so there is nothing to attribute a line to. Those lines are still recalled for the run: every one of them was refused, and a refused line is the one most worth getting back. When ebc5755 routes a merge line to the board its card names, that board's file is the one to append to
|
||||
- **The position is on `Prompt` and the lines are on `Recall`**, so closing the prompt forgets the position and not the lines: the next `:` opens at the end of the list again, which is where a shell opens. `pending` holds the half typed line `up` walked away from, and walking `down` past the newest entry puts it back, so leaving a command to look for an older one never costs it
|
||||
- **The ends are stops, not wraps.** `up` on the oldest line leaves it up rather than cycling round to the newest, which is what a shell does with it; `down` with no walk under way does nothing, since there is nothing in front of a line still being typed and emptying the row would be a keypress that destroys work. **An empty recall does nothing at all**, and that includes leaving the line alone, or `up` on a board nobody has typed at would be a way to lose what is half written
|
||||
- **The line is kept before anything can refuse it.** A refused line never reached a handler and the fix is usually two characters, which is what the walk exists to save. Consecutive duplicates are kept once, against what is already held, so the rule spans runs as well as one sitting; a blank line is no command and is not kept. Nothing is trimmed
|
||||
- **A failed write is silent, and an unreadable file is an empty recall.** The line is in memory either way, so the walk works for the run on a board whose folder cannot be written, and a board with no history yet is the ordinary case rather than something to say. A notice about a history file would be about the one thing the reader did not ask for
|
||||
- **`.wlhistory` is not in `digest`.** Appending to it must not read as the tree moving, or every command typed would provoke a reload of every board on top of the one `run` already does
|
||||
|
||||
### Splitting a Typed Line
|
||||
- **`split_line` is the whole module, and it knows nothing about `Board`.** The command prompt reads one string and clap reads an argv, so `comment 1b78a24 the offset was never passed` has to be tokenised before anything can parse it: split on whitespace it is five arguments and `comment` takes two. A pure function over the line and the cursor is what makes every rule reachable from a unit test, and it is in a file of its own rather than in `tui.rs`, which is eleven thousand lines already
|
||||
- **The rules are the shell's, because that is what the prompt promises**: the line is spelled there exactly as it is spelled in the shell. Runs of whitespace separate arguments, single and double quotes group one, a backslash escapes the next character *except* inside single quotes where it is a backslash, and an explicitly empty `''` is an argument that exists and is empty — which is what `--title ""` being a usage error rather than a silent clear depends on. A leading hyphen is not special here: whether `--foo` is a flag or the text of a criterion is clap's question, and `PROSE` already answers it
|
||||
@@ -449,7 +483,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **A mechanical entry renders as one line and a comment as it always did.** A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to `Kind::LABEL_WIDTH`, `campaign` being the longest of the four, so the bodies line up under each other
|
||||
- **A campaign entry records `Campaign::name`, the codename or failing that the title, never the uuid the field holds.** Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. A `before` uuid the board no longer has reads `_missing_`, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from `_Not set_` (f774a33)
|
||||
- **`--actor` is on every command that writes an entry**, spelled from one `ACTOR_HELP` in `command.rs`: a flag documented differently on each command reads as four flags. `--actor-from-git` rides beside it from its own one string, the same way. On `chown` it sits beside `user`, which is the ticket's new assignee — the two are different questions and that command answers both
|
||||
- **`set --actor` reaches only the entry `--tags` writes**, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries
|
||||
- **`set --actor` reaches only the entry `--tags` writes**, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries. `append --actor` is the same flag for the same reason: `append --tags` moves the same field, so it writes the same `Kind::Tags` entry, and a tag added without replacing the rest would otherwise be the one tag change the log missed
|
||||
|
||||
### Shipping the Agent Assets
|
||||
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
|
||||
|
||||
Generated
+1
-1
@@ -1503,7 +1503,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.32.14"
|
||||
version = "0.32.20"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.32.14"
|
||||
version = "0.32.20"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
@@ -5,15 +5,37 @@
|
||||
# release cannot end up half-done: no version bump left untagged, no tag without
|
||||
# a bump.
|
||||
|
||||
.PHONY: help patch minor major version release install
|
||||
.PHONY: help check patch minor major version release install
|
||||
|
||||
help:
|
||||
@echo "make check fmt, clippy and the suite, in that order"
|
||||
@echo "make patch bump $(CURRENT) -> next patch, amend into HEAD, tag"
|
||||
@echo "make minor bump $(CURRENT) -> next minor, amend into HEAD, tag"
|
||||
@echo "make major bump $(CURRENT) -> next major, amend into HEAD, tag"
|
||||
@echo "make version print the current version"
|
||||
@echo "make install cargo install --path . && worklane install-skill"
|
||||
|
||||
# The one command to run before committing. AGENTS.md pins fmt and clippy as clean and
|
||||
# 83d31cd is what happens when only memory enforces that: fmt drifted to about 160 places
|
||||
# across every file with the tool installed and configured the whole time. This is not CI,
|
||||
# which a single-author tool with no pipeline anywhere does not want, and not a hook, which
|
||||
# is a per-clone opt-in the way `blame.ignoreRevsFile` is. It is one name to type, so
|
||||
# "remember to run fmt, clippy and the tests" becomes "run make check".
|
||||
#
|
||||
# Cheapest first, so a formatting slip is reported in a second rather than after the suite.
|
||||
# `--all-targets` on clippy, matching the rule in AGENTS.md, so the tests are linted too.
|
||||
# `-D warnings` is what makes clippy's opinion an exit code: the rule says clean, and a
|
||||
# warning printed into a wall of cargo output is not clean, it is unread.
|
||||
#
|
||||
# Completions are in the suite rather than a step of their own. `cargo test` sources the
|
||||
# generated script into a real fish and asks it for candidates, so "check tests, check
|
||||
# completions" is one command already, and a second target would be a second thing to
|
||||
# remember. The fish tests skip when fish is not installed, printing that they did.
|
||||
check:
|
||||
cargo fmt --check
|
||||
cargo clippy --all-targets -- -D warnings
|
||||
cargo test
|
||||
|
||||
# Read from the [package] table of Cargo.toml, which is the version the binary
|
||||
# reports through `--version`, so it is the single source of truth. The name is
|
||||
# what finds this crate's own entry in Cargo.lock.
|
||||
|
||||
@@ -12,7 +12,7 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three. Ends with the ticket's history: every comment on it and every change to its status, owner or tags, oldest first, each naming who made it |
|
||||
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions. `--status discarded` is exempt and reachable from anywhere, for a ticket that will not be done; leaving `discarded` is a backward move and needs `-f`. Discarding is refused while open tickets are blocked by the ticket, `-f` overrides. Records a `status` entry in the ticket's history, after the move: a refused or no-op move records nothing. `--actor` names the writer of that entry |
|
||||
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused. `--tags` records a `tags` entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; `--actor` names the writer of that entry |
|
||||
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
|
||||
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`, or to the tags with `--tags`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last. `--tags` keeps the tags the ticket already carries, ignores one it already has, and takes several as a repeated flag or separated by commas, the way the field itself is written; it is the counterpart to `set --tags`, which replaces the whole field. It records a `tags` entry in the ticket's history, and `--actor` names the writer of that entry, this command's only logged field as it is `set`'s. Emptying a field is `set --clear`, which has no counterpart here |
|
||||
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning, and a derived row that reads exactly like a stored one is drawn once. `relates to` on a ticket whose target already stores it reports no change, since it is the same edge; `blocked by` and `regression of` read differently from the far end, so a mutual pair is two rows. `mv` refuses to move a ticket blocked by one that is not done, unless `-f`. `--clear <kind> <target>` takes an edge off instead, repeatable, the kind spelled either way, `blocked-by` or `blocked by`. The target resolves against the edges the ticket holds first, by id prefix, which is the only way to reach one whose ticket has been deleted, then as an ordinary ticket search. An edge the ticket does not hold reports no change; a target naming nothing at all is an error. Recording and clearing the same edge in one call is refused |
|
||||
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to. Records an `owner` entry in the ticket's history, with the owner before and after; `--actor` names who made the change, which is not the same as the user argument |
|
||||
| `worklane check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
|
||||
@@ -88,6 +88,17 @@ the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer who
|
||||
and the writer never learns the reader left, giving 0. Only output past that gets far
|
||||
enough to be cut off. Either way nothing is printed to stderr.
|
||||
|
||||
## Checking
|
||||
|
||||
```sh
|
||||
make check # cargo fmt --check, clippy -D warnings, cargo test
|
||||
```
|
||||
|
||||
One command, cheapest first, and the whole of what enforces the formatting and lint rules:
|
||||
there is no CI here and no hook. The completion tests inside it source the generated script
|
||||
into a real fish and ask it what it would offer, so they skip, saying so, on a machine
|
||||
without fish.
|
||||
|
||||
## Releasing
|
||||
|
||||
```sh
|
||||
|
||||
+14
-8
@@ -169,16 +169,21 @@ worklane set 1b78a24 --clear due # take a value away again
|
||||
worklane set 1b78a24 --clear tags --clear plan # as many fields as you like
|
||||
worklane append 1b78a24 --acceptance "One more criterion"
|
||||
worklane append 1b78a24 --description "What was learned since."
|
||||
worklane append 1b78a24 --tags tui # add a tag, keeping the ones there
|
||||
worklane chown alice 1b78a24 # hand the ticket to someone
|
||||
worklane chown --clear 1b78a24 # hand it back to nobody
|
||||
```
|
||||
|
||||
`set` replaces, `append` adds, `--clear` empties. `set --tags` overwrites the whole
|
||||
field: to add a tag to a ticket that already carries one, replace the value with every
|
||||
tag separated by commas. Neither `set` nor `append` has `--owner` or `--status`: owner
|
||||
is `chown`'s and status is `mv`'s, so each field has exactly one writer. A field set to
|
||||
the value it already holds is reported unchanged and nothing is written, and so is a
|
||||
field cleared that was already unset.
|
||||
field, so **use `append --tags` to add a tag to a ticket that already carries some**: it
|
||||
keeps what is there, and a tag the ticket already has is reported as no change rather
|
||||
than added twice, so you do not have to read the ticket first. Several in one call by
|
||||
repeating the flag or by separating them with commas, `--tags "bug, tui"`, since that is
|
||||
how the field itself is written. Reach for `set --tags` when the whole list is being
|
||||
replaced, and `set --clear tags` to empty it: `append` has neither. Neither `set` nor
|
||||
`append` has `--owner` or `--status`: owner is `chown`'s and status is `mv`'s, so each
|
||||
field has exactly one writer. A field set to the value it already holds is reported
|
||||
unchanged and nothing is written, and so is a field cleared that was already unset.
|
||||
|
||||
**`--clear` takes the field as its value**, one of `due`, `tags`, `priority`,
|
||||
`description`, `acceptance` or `plan`, and repeats. It writes back exactly what `add`
|
||||
@@ -339,8 +344,8 @@ existing ticket will have been written from a different angle.
|
||||
|
||||
`show` ends with a HISTORY block: every comment on the ticket and every change to its
|
||||
status, owner, tags or campaign, oldest first, each naming who made it. You do not write
|
||||
these by hand. `mv`, `chown`, `set --tags` and `assign` record themselves, and a call
|
||||
that changes nothing records nothing. A campaign move is recorded by codename, or by
|
||||
these by hand. `mv`, `chown`, `set --tags`, `append --tags` and `assign` record
|
||||
themselves, and a call that changes nothing records nothing. A campaign move is recorded by codename, or by
|
||||
title for a campaign that has none, not by the uuid the field holds.
|
||||
|
||||
```
|
||||
@@ -380,7 +385,8 @@ you to move a ticket, or to put words on the board as their comment, so name the
|
||||
the flag — the move was theirs and the words are theirs, and an entry carrying your name
|
||||
reads later as though you decided both. Otherwise leave it off, unless your instructions
|
||||
say to use it. It is spelled the same on every command that writes an entry: `comment`,
|
||||
`mv`, `chown`, `set` and `assign`.
|
||||
`mv`, `chown`, `set`, `append` and `assign`. On the last two it reaches only the entry
|
||||
`--tags` writes, since that is the one field either of them logs.
|
||||
|
||||
Acting for the person without knowing how they spell themselves? `--actor-from-git`
|
||||
attributes the entry to the detected git user instead of `WORKLANE_ACTOR`, so their name
|
||||
|
||||
+16
-3
@@ -358,7 +358,7 @@ export const set = tool({
|
||||
|
||||
export const append = tool({
|
||||
description:
|
||||
"Add to a section of an existing worklane ticket without replacing what is there. The description gains a new paragraph; acceptance criteria and plan steps are added to the end of their lists, with steps numbered on from the last. Ticked criteria and handwritten content are left alone. To replace a section outright, use set.",
|
||||
"Add to an existing worklane ticket without replacing what is there. The description gains a new paragraph; acceptance criteria and plan steps are added to the end of their lists, with steps numbered on from the last; tags are added to the ones the ticket already carries. Ticked criteria and handwritten content are left alone. To replace a section or the whole tag list outright, use set.",
|
||||
args: {
|
||||
ticket: tool.schema
|
||||
.string()
|
||||
@@ -375,6 +375,14 @@ export const append = tool({
|
||||
.string()
|
||||
.describe("Implementation plan steps to add, one per line.")
|
||||
.optional(),
|
||||
tags: tool.schema
|
||||
.string()
|
||||
.describe("Tags to add, comma separated, keeping the ones the ticket already carries. A tag it already has is reported as no change rather than added twice, so the ticket does not have to be read first.")
|
||||
.optional(),
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Who the entry is attributed to. Only reaches the entry tags writes, since that is the one field of this command's that is logged. If omitted, WORKLANE_ACTOR is used, then the git user.")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
if (!args.ticket) {
|
||||
@@ -395,9 +403,14 @@ export const append = tool({
|
||||
if (args.plan) {
|
||||
itemLines(args.plan).forEach((line: string) => cmd.push("--plan", line));
|
||||
}
|
||||
if (args.tags) cmd.push("--tags", args.tags);
|
||||
// Last, and not counted as a field: the length check below is what refuses a call
|
||||
// that names nothing to add, and an actor alone adds nothing. Same shape as set.
|
||||
const fields = cmd.length;
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
if (cmd.length === 2) {
|
||||
return "Error appending: give at least one section to add to";
|
||||
if (fields === 2) {
|
||||
return "Error appending: give at least one field to add to";
|
||||
}
|
||||
|
||||
try {
|
||||
|
||||
+26
-4
@@ -858,14 +858,15 @@ impl ChownArgs {
|
||||
}
|
||||
}
|
||||
|
||||
/// `append` only offers the sections that hold multiple lines, since appending to a
|
||||
/// scalar has no meaning.
|
||||
/// `append` offers the fields something can be added to without disturbing what is
|
||||
/// already in them: the three sections that hold multiple lines, and Tags, which is a
|
||||
/// list. Appending to a scalar has no meaning, so there is no `--priority` or `--due`.
|
||||
#[derive(clap::Args)]
|
||||
#[command(group(
|
||||
clap::ArgGroup::new("append_fields")
|
||||
.required(true)
|
||||
.multiple(true)
|
||||
.args(["description", "acceptance", "plan"])
|
||||
.args(["description", "acceptance", "plan", "tags"])
|
||||
))]
|
||||
pub struct AppendArgs {
|
||||
/// Ticket UUID or title
|
||||
@@ -882,6 +883,24 @@ pub struct AppendArgs {
|
||||
/// Add implementation plan steps, numbered on from the last. Repeat the flag
|
||||
#[arg(short, long, allow_hyphen_values = PROSE)]
|
||||
pub plan: Vec<String>,
|
||||
|
||||
/// Add tags, keeping the ones the ticket already carries. Repeat the flag, or
|
||||
/// separate them with commas
|
||||
///
|
||||
/// `non_empty` rather than the `clearable` that `set --tags` takes. That message
|
||||
/// names `--clear`, and this command has none: emptying the field is
|
||||
/// `set --clear tags`, so pointing at a flag that is not here would send the caller
|
||||
/// looking for it on `append`.
|
||||
#[arg(short = 'g', long, value_parser = non_empty)]
|
||||
pub tags: Vec<String>,
|
||||
|
||||
/// Only reaches the entry `--tags` writes, since that is the one field of this
|
||||
/// command's that is logged, exactly as on `set`
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
pub actor: Option<String>,
|
||||
|
||||
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
|
||||
pub actor_from_git: bool,
|
||||
}
|
||||
|
||||
/// `relate` is the only writer of the Relations section, the way `chown` is the only
|
||||
@@ -1080,6 +1099,9 @@ mod tests {
|
||||
|
||||
// A guard on the walker itself: if it stopped finding commands, every assertion
|
||||
// above would pass by never running.
|
||||
assert_eq!(seen, 5, "expected comment, mv, chown, set and assign to carry --actor");
|
||||
assert_eq!(
|
||||
seen, 6,
|
||||
"expected comment, mv, chown, set, append and assign to carry --actor"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
+81
-13
@@ -64,12 +64,22 @@ pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [
|
||||
/// Options whose value is a campaign.
|
||||
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
|
||||
/// Options whose value is a tag.
|
||||
/// Options whose value is a tag, as the command that takes it and the flag's long name.
|
||||
///
|
||||
/// 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"];
|
||||
///
|
||||
/// Pairs rather than the flat list the other flag lists are, because the two spellings
|
||||
/// differ: `ls --tag` filters on one and `append --tags` adds them, so a single rule
|
||||
/// naming both options would tell fish that each command takes the other's flag. One
|
||||
/// rule per pair instead.
|
||||
///
|
||||
/// `add --tags` and `set --tags` are deliberately absent. Both take the *whole* list, so
|
||||
/// the token being completed is `bug,tui` and fish replaces a token entire: offering one
|
||||
/// tag there would throw away the ones already typed. `append --tags` is the one where
|
||||
/// naming a single tag is the ordinary call.
|
||||
pub const TAG_FLAGS: [(&str, &str); 2] = [("ls", "tag"), ("append", "tags")];
|
||||
|
||||
/// Nested commands whose first argument is a tag the board already has.
|
||||
///
|
||||
@@ -110,7 +120,16 @@ fn fish_dynamic() -> String {
|
||||
.collect::<Vec<_>>()
|
||||
.join("; or ");
|
||||
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
|
||||
let tag_flags = flag_list(&TAG_FLAGS);
|
||||
let tag_flags = TAG_FLAGS
|
||||
.iter()
|
||||
.map(|(command, flag)| {
|
||||
format!(
|
||||
"complete -c worklane -n '__worklane_command_is {command}' -l {flag} \\\n \
|
||||
-x -a '(worklane tags | cut -f1,3)'"
|
||||
)
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n");
|
||||
let tag_nested = TAG_NESTED_COMMANDS
|
||||
.iter()
|
||||
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
|
||||
@@ -218,8 +237,10 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
|
||||
# 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)'
|
||||
#
|
||||
# One rule per command, from `TAG_FLAGS`: `ls --tag` and `append --tags` are spelled
|
||||
# differently, so a single rule naming both options would offer each under the other.
|
||||
{tag_flags}
|
||||
|
||||
# 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
|
||||
@@ -410,14 +431,28 @@ mod tests {
|
||||
/// about what the fish block is missing, which is a test's question.
|
||||
const TAG_NEW_COMMANDS: [(&str, &str); 1] = [("tags", "add")];
|
||||
|
||||
/// Options taking a whole comma-separated list of tags rather than one.
|
||||
///
|
||||
/// `add --tags` and `set --tags` write the field entire, so what is being typed at the
|
||||
/// cursor is `bug,tui` and fish replaces a token whole: a rule offering one tag there
|
||||
/// would throw away the ones already in the token. `append --tags` adds to what is
|
||||
/// there, so a single tag is the ordinary value and it earns a rule. Recorded rather
|
||||
/// than skipped, for the reason `TAG_NEW_COMMANDS` is: the next `--tags` has to say
|
||||
/// which of the two it is.
|
||||
const TAG_LIST_FLAGS: [(&str, &str); 2] = [("add", "tags"), ("set", "tags")];
|
||||
|
||||
/// 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.
|
||||
///
|
||||
/// Both spellings are walked, `tag` and `tags`: they are the same object under two
|
||||
/// argument names, and looking at only the singular is how `set --tags` went years
|
||||
/// without anybody deciding whether it wanted a rule.
|
||||
#[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" {
|
||||
if !matches!(arg.get_id().as_str(), "tag" | "tags") {
|
||||
continue;
|
||||
}
|
||||
seen += 1;
|
||||
@@ -440,13 +475,18 @@ mod tests {
|
||||
continue;
|
||||
};
|
||||
|
||||
let pair = (name.as_str(), long);
|
||||
assert!(
|
||||
TAG_FLAGS.contains(&long),
|
||||
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
|
||||
TAG_FLAGS.contains(&pair) || TAG_LIST_FLAGS.contains(&pair),
|
||||
"`worklane {name} --{long}` takes a tag, so it belongs in TAG_FLAGS if one \
|
||||
tag is the ordinary value and TAG_LIST_FLAGS if the value is the whole list"
|
||||
);
|
||||
}
|
||||
|
||||
assert_eq!(seen, 3, "expected ls --tag, tags add and tags set");
|
||||
assert_eq!(
|
||||
seen, 6,
|
||||
"expected ls --tag, tags add, tags set, add --tags, set --tags and append --tags"
|
||||
);
|
||||
}
|
||||
|
||||
/// **Every rule naming an option has to say which command it belongs to.** A bare
|
||||
@@ -472,8 +512,30 @@ mod tests {
|
||||
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}");
|
||||
|
||||
// Every list that names a top-level command, not only the ticket ones. The others
|
||||
// were reachable only through the rule counts below, which fail with `expected 3,
|
||||
// got 4` and name nothing: a stale entry is a `complete` line whose condition never
|
||||
// matches, so fish offers nothing and says nothing about why.
|
||||
let top = TICKET_COMMANDS
|
||||
.iter()
|
||||
.chain(TICKET_SECOND_COMMANDS.iter())
|
||||
.chain(CAMPAIGN_COMMANDS.iter())
|
||||
.copied()
|
||||
.chain(TAG_FLAGS.iter().map(|(command, _)| *command));
|
||||
|
||||
for name in top {
|
||||
assert!(known.contains(&name), "no such subcommand: {name}");
|
||||
}
|
||||
|
||||
for (parent, child) in CAMPAIGN_NESTED_COMMANDS.iter().chain(TAG_NESTED_COMMANDS.iter()) {
|
||||
let sub = cli
|
||||
.find_subcommand(parent)
|
||||
.unwrap_or_else(|| panic!("no such subcommand: {parent}"));
|
||||
assert!(
|
||||
sub.find_subcommand(child).is_some(),
|
||||
"`worklane {parent}` has no `{child}` subcommand"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -587,10 +649,16 @@ mod tests {
|
||||
.filter(|line| line.contains("(worklane tags"))
|
||||
.collect();
|
||||
|
||||
// **Hardcoded on purpose, and not derivable from the lists above.** This number is
|
||||
// what catches an entry naming a command or a flag that does not exist: the walkers
|
||||
// go clap → list and never see an extra, so a bogus `("bogus", "nope")` in
|
||||
// `TAG_FLAGS` produces a fourth rule and only this count notices. Writing it as
|
||||
// `TAG_FLAGS.len() + TAG_NESTED_COMMANDS.len()` would grow with the bogus entry and
|
||||
// pass, which is the improvement to not make.
|
||||
assert_eq!(
|
||||
reading.len(),
|
||||
2,
|
||||
"expected the ls --tag rule and the tags set one: {reading:?}"
|
||||
3,
|
||||
"expected the ls --tag rule, the append --tags one and the tags set one: {reading:?}"
|
||||
);
|
||||
for line in reading {
|
||||
assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}");
|
||||
|
||||
@@ -1135,12 +1135,83 @@ pub fn cmd_append(args: &AppendArgs, start: &Path, sink: &mut Sink) -> Result<()
|
||||
changed.push(section.label);
|
||||
}
|
||||
|
||||
// Through `apply`, unlike the sections above: appending a section always adds
|
||||
// something, and appending a tag the ticket already carries is the no-op this flag
|
||||
// exists to make free.
|
||||
if !args.tags.is_empty() {
|
||||
let next =
|
||||
set_metadata_field(&content, "Tags", &appended_tags(&content, &args.tags)?, &title)?;
|
||||
apply(&mut content, &mut changed, "tags", next);
|
||||
}
|
||||
|
||||
// The only way to reach here with nothing to write is a `--tags` the ticket already
|
||||
// satisfied, since every other field on this command adds or refuses. Reported in the
|
||||
// words `set` uses for the same answer.
|
||||
if changed.is_empty() {
|
||||
report(sink, &[], &title, "Appended to")?;
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
|
||||
|
||||
// Tags are logged wherever they change, so the one command that adds to them without
|
||||
// replacing them logs too. Same shape as `set`'s, down to the before and after being
|
||||
// read off the field rather than off the flag: what the entry records is where the
|
||||
// field went, not what this call asked for.
|
||||
if changed.contains(&"tags") {
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&uuid,
|
||||
Kind::Tags,
|
||||
&change(
|
||||
&parse_ticket_field(&original, "Tags"),
|
||||
&parse_ticket_field(&content, "Tags"),
|
||||
),
|
||||
&resolve_actor(args.actor.as_deref(), args.actor_from_git),
|
||||
"",
|
||||
)?;
|
||||
}
|
||||
|
||||
report(sink, &changed, &title, "Appended to")?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// The ticket's tags with the call's merged onto the end, or the refusal for a call that
|
||||
/// named none.
|
||||
///
|
||||
/// A tag the ticket already carries is not added a second time, which is the whole
|
||||
/// difference from `set --tags`: appending means the caller does not have to know what is
|
||||
/// there already, so naming one that is reports no change rather than doubling it. New
|
||||
/// ones go on the end in the order they were given rather than sorted, so the field goes
|
||||
/// on reading as what was added when.
|
||||
///
|
||||
/// The values are split on commas the way the stored field is, so `--tags "bug, tui"`
|
||||
/// names two tags and matches the two a ticket carrying them already holds. Without that
|
||||
/// the pair would land as a single tag nothing can filter by, which is what `tag_value`
|
||||
/// refuses outright for the vocabulary; here it is split instead, because `set --tags`
|
||||
/// takes the comma form on this same field and refusing it on its counterpart would be a
|
||||
/// trap.
|
||||
///
|
||||
/// A call whose every value comes out blank is refused rather than written, the way
|
||||
/// [`appended_items`] refuses one: `--tags ","` names nothing, and writing the field back
|
||||
/// unchanged would report an append that never happened. Emptying the field is
|
||||
/// `set --clear tags`.
|
||||
fn appended_tags(content: &str, values: &[String]) -> Result<String> {
|
||||
let added: Vec<String> = values.iter().flat_map(|value| split_tags(value)).collect();
|
||||
if added.is_empty() {
|
||||
return Err(anyhow!("Nothing to append to the tags: every value given was blank"));
|
||||
}
|
||||
|
||||
let mut tags = parse_tags(content);
|
||||
for tag in added {
|
||||
if !tags.contains(&tag) {
|
||||
tags.push(tag);
|
||||
}
|
||||
}
|
||||
|
||||
Ok(tags.join(", "))
|
||||
}
|
||||
|
||||
/// Record a relation from one ticket to another.
|
||||
///
|
||||
/// One side is written and the inverse is derived wherever it is shown. `blocked by`
|
||||
|
||||
+113
-68
@@ -1,3 +1,5 @@
|
||||
use std::path::Path;
|
||||
|
||||
use anyhow::Result;
|
||||
use clap::Parser;
|
||||
|
||||
@@ -8,8 +10,9 @@ mod completions;
|
||||
mod handlers;
|
||||
mod history;
|
||||
mod install;
|
||||
/// Nothing in the binary splits a line yet: the prompt that will is 3686dd6, and the
|
||||
/// allow goes when it lands. The tests are what drive it in the meantime.
|
||||
/// The command prompt reads `split_line` and `unclosed`; `cursor_arg` and `at_new_arg` are
|
||||
/// what completing an argument needs and nothing reads them yet, so the allow stays until
|
||||
/// 00a14e7 and 952a9f8 land. The tests are what drive them in the meantime.
|
||||
#[cfg_attr(not(test), allow(dead_code))]
|
||||
mod split;
|
||||
mod tag;
|
||||
@@ -49,76 +52,16 @@ fn main() -> Result<()> {
|
||||
let mut sink = Sink::std();
|
||||
|
||||
let result = match cli.command {
|
||||
// The board is the one thing `dispatch` does not run, and it is matched here
|
||||
// rather than there because it is the *caller* of that table rather than an entry
|
||||
// in it: a `tui` reached from the command prompt would enter the alternate screen
|
||||
// a second time from inside the draw loop. `dispatch` refuses it in those words.
|
||||
//
|
||||
// No subcommand opens the board, the way a bare `frig` does, and with no path
|
||||
// it opens the board above the working directory.
|
||||
None => run_tui(&[], &start),
|
||||
Some(Command::Tui { paths }) => run_tui(&paths, &start),
|
||||
Some(Command::Init) => cmd_init(&start, &mut sink),
|
||||
Some(Command::Add(args)) => cmd_add(&args, &start, &mut sink),
|
||||
Some(Command::Ls(args)) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_ls(&args, &worklane_dir, &mut sink)
|
||||
}
|
||||
Some(Command::Show { id }) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_show(&id, &worklane_dir, &mut sink)
|
||||
}
|
||||
Some(Command::Mv(args)) => cmd_mv(&args, &start, &mut sink),
|
||||
Some(Command::Set(args)) => cmd_set(&args, &start, &mut sink),
|
||||
Some(Command::Append(args)) => cmd_append(&args, &start, &mut sink),
|
||||
Some(Command::Relate(args)) => cmd_relate(&args, &start, &mut sink),
|
||||
Some(Command::Chown(args)) => cmd_chown(&args, &start, &mut sink),
|
||||
Some(Command::Check(args)) => cmd_check(&args, true, &start, &mut sink),
|
||||
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start, &mut sink),
|
||||
Some(Command::Comment {
|
||||
ticket,
|
||||
body,
|
||||
actor,
|
||||
actor_from_git,
|
||||
}) => cmd_comment(&ticket, &body, &actor, actor_from_git, &start, &mut sink),
|
||||
Some(Command::Campaign { command }) => match command {
|
||||
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start, &mut sink),
|
||||
CampaignCommand::Ls { ids } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_ls(&worklane_dir, ids, &mut sink)
|
||||
}
|
||||
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start, &mut sink),
|
||||
CampaignCommand::Append(args) => cmd_campaign_append(&args, &start, &mut sink),
|
||||
CampaignCommand::Show { campaign } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_show(&campaign, &worklane_dir, &mut sink)
|
||||
}
|
||||
},
|
||||
Some(Command::Assign {
|
||||
campaign,
|
||||
ticket,
|
||||
actor,
|
||||
actor_from_git,
|
||||
}) => cmd_assign(&campaign, &ticket, &actor, actor_from_git, &start, &mut sink),
|
||||
// The bare form and `ls` are one arm: `worklane tags` was the listing before the
|
||||
// group existed and the fish completion still calls it that way, so the two
|
||||
// spellings cannot be allowed to drift into two behaviours.
|
||||
Some(Command::Tags { command }) => match command {
|
||||
None | Some(TagCommand::Ls) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_tags(&worklane_dir, &mut sink)
|
||||
}
|
||||
Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start, &mut sink),
|
||||
Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start, &mut sink),
|
||||
},
|
||||
// No board either, for the reason `install-skill` has none: a completion script
|
||||
// is generated from the clap definition and is the same wherever it is run.
|
||||
Some(Command::Completions { shell }) => {
|
||||
completions::generate(shell, sink.as_write()).map_err(Into::into)
|
||||
}
|
||||
// No board is looked for: the point of the skill is to teach an agent worklane
|
||||
// before there is a `.worklane` anywhere.
|
||||
Some(Command::InstallSkill { skill, force, print }) => {
|
||||
cmd_install_skill(skill.as_deref(), force, print, &mut sink)
|
||||
}
|
||||
// No board either, and one agent rather than both: opencode loads the tool file,
|
||||
// Claude Code has no path for one.
|
||||
Some(Command::InstallTool { force, print }) => cmd_install_tool(force, print, &mut sink),
|
||||
Some(command) => dispatch(&command, &start, &mut sink),
|
||||
};
|
||||
|
||||
// The board (and every handler) own their own writing, so flush what the last one
|
||||
@@ -127,6 +70,93 @@ fn main() -> Result<()> {
|
||||
result
|
||||
}
|
||||
|
||||
/// Run one parsed command against the board at or above `start`, saying what it did
|
||||
/// through `sink`.
|
||||
///
|
||||
/// **The one mapping from a parsed command to the function that performs it.** `main`
|
||||
/// calls it with the process's stdout and the working directory; the command prompt on
|
||||
/// the board calls it with a buffer and the selected tab's own root, and reads back what
|
||||
/// the handler said. A second copy of this match inside `tui.rs` would be a copy that
|
||||
/// drifted the first time a command was added, and it would drift *silently*, since both
|
||||
/// halves would go on compiling.
|
||||
///
|
||||
/// A command added to [`Command`] therefore lands here once and is runnable from both.
|
||||
/// The match is exhaustive for exactly that reason: there is no `_` arm for a new verb to
|
||||
/// fall into and do nothing.
|
||||
pub fn dispatch(command: &Command, start: &Path, sink: &mut Sink) -> Result<()> {
|
||||
match command {
|
||||
// Reachable only from the prompt, since `main` takes this arm before it gets
|
||||
// here. A board is not something a board can open.
|
||||
Command::Tui { .. } => Err(anyhow::anyhow!("`tui` opens a board, and you are on one")),
|
||||
Command::Init => cmd_init(start, sink),
|
||||
Command::Add(args) => cmd_add(args, start, sink),
|
||||
Command::Ls(args) => {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
cmd_ls(args, &worklane_dir, sink)
|
||||
}
|
||||
Command::Show { id } => {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
cmd_show(id, &worklane_dir, sink)
|
||||
}
|
||||
Command::Mv(args) => cmd_mv(args, start, sink),
|
||||
Command::Set(args) => cmd_set(args, start, sink),
|
||||
Command::Append(args) => cmd_append(args, start, sink),
|
||||
Command::Relate(args) => cmd_relate(args, start, sink),
|
||||
Command::Chown(args) => cmd_chown(args, start, sink),
|
||||
Command::Check(args) => cmd_check(args, true, start, sink),
|
||||
Command::Uncheck(args) => cmd_check(args, false, start, sink),
|
||||
Command::Comment {
|
||||
ticket,
|
||||
body,
|
||||
actor,
|
||||
actor_from_git,
|
||||
} => cmd_comment(ticket, body, actor, *actor_from_git, start, sink),
|
||||
Command::Campaign { command } => match command {
|
||||
CampaignCommand::Add(args) => cmd_campaign_add(args, start, sink),
|
||||
CampaignCommand::Ls { ids } => {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
cmd_campaign_ls(&worklane_dir, *ids, sink)
|
||||
}
|
||||
CampaignCommand::Set(args) => cmd_campaign_set(args, start, sink),
|
||||
CampaignCommand::Append(args) => cmd_campaign_append(args, start, sink),
|
||||
CampaignCommand::Show { campaign } => {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
cmd_campaign_show(campaign, &worklane_dir, sink)
|
||||
}
|
||||
},
|
||||
Command::Assign {
|
||||
campaign,
|
||||
ticket,
|
||||
actor,
|
||||
actor_from_git,
|
||||
} => cmd_assign(campaign, ticket, actor, *actor_from_git, start, sink),
|
||||
// The bare form and `ls` are one arm: `worklane tags` was the listing before the
|
||||
// group existed and the fish completion still calls it that way, so the two
|
||||
// spellings cannot be allowed to drift into two behaviours.
|
||||
Command::Tags { command } => match command {
|
||||
None | Some(TagCommand::Ls) => {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
cmd_tags(&worklane_dir, sink)
|
||||
}
|
||||
Some(TagCommand::Add(args)) => cmd_tag_add(args, start, sink),
|
||||
Some(TagCommand::Set(args)) => cmd_tag_set(args, start, sink),
|
||||
},
|
||||
// No board either, for the reason `install-skill` has none: a completion script
|
||||
// is generated from the clap definition and is the same wherever it is run.
|
||||
Command::Completions { shell } => {
|
||||
completions::generate(*shell, sink.as_write()).map_err(Into::into)
|
||||
}
|
||||
// No board is looked for: the point of the skill is to teach an agent worklane
|
||||
// before there is a `.worklane` anywhere.
|
||||
Command::InstallSkill { skill, force, print } => {
|
||||
cmd_install_skill(skill.as_deref(), *force, *print, sink)
|
||||
}
|
||||
// No board either, and one agent rather than both: opencode loads the tool file,
|
||||
// Claude Code has no path for one.
|
||||
Command::InstallTool { force, print } => cmd_install_tool(*force, *print, sink),
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------- tui --
|
||||
|
||||
/// Restore the terminal whatever happens.
|
||||
@@ -219,6 +249,15 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
continue;
|
||||
}
|
||||
|
||||
// And the command prompt, third, on the same contract: while a command is being
|
||||
// typed `q` is a letter, `d` leaves the columns alone and `tab` stays out of the
|
||||
// project tabs. It takes the screen because enter runs the command and then has
|
||||
// to bring the ticket it moved back into view. The rule is `Board::prompt_key`,
|
||||
// where a test can reach it.
|
||||
if board.prompt_key(key, screen) {
|
||||
continue;
|
||||
}
|
||||
|
||||
match key.code {
|
||||
// One arm, because the two keys mean one thing: close what is open, and
|
||||
// quit when there is nothing left to close. Two arms carrying one rule
|
||||
@@ -262,6 +301,12 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
// at an open picker is taken by `picker_key` to open the picker's own
|
||||
// query, so this arm is only ever the way in to the board's prompt.
|
||||
KeyCode::Char('/') => board.open_search(),
|
||||
// The way in to the command prompt, and the same single-shot arm `/` is:
|
||||
// from the next keypress on, `prompt_key` above has the keyboard. A `:`
|
||||
// typed into either open prompt is a character there and one pressed at an
|
||||
// open picker is swallowed by it, so this arm is only ever the way in from
|
||||
// the board itself. Free of every existing binding.
|
||||
KeyCode::Char(':') => board.open_prompt(),
|
||||
// `y` as in yank, for the readers this board is for, and the only letter
|
||||
// left that a vim hand would reach for. The clipboard is handed in rather
|
||||
// than reached for inside `Board`, so the suite can drive both answers.
|
||||
|
||||
+1976
-5
File diff suppressed because it is too large
Load Diff
+50
-1
@@ -303,6 +303,42 @@ pub fn color_text(text: &str, color: Color) -> String {
|
||||
paint(text, color, should_use_colors())
|
||||
}
|
||||
|
||||
/// `text` with every ANSI escape sequence taken out of it.
|
||||
///
|
||||
/// The inverse of what [`paint`] writes, and the guard at the seam where a handler's
|
||||
/// words become something the board draws: ratatui prints an escape as literal bytes
|
||||
/// rather than obeying it, so a painted status reaches the screen as `\x1b[33m` and
|
||||
/// the word after it.
|
||||
///
|
||||
/// A [`Sink`] the board owns is plain, so this is not about a handler's ordinary
|
||||
/// output. It is about the strings that never go through one: an error message is
|
||||
/// built with `color_text`, which asks the *process* about its stdout, and under the
|
||||
/// board that answers yes about a terminal the message is not going to.
|
||||
pub fn without_escapes(text: &str) -> String {
|
||||
let mut out = String::with_capacity(text.len());
|
||||
let mut chars = text.chars();
|
||||
|
||||
while let Some(c) = chars.next() {
|
||||
if c != '\x1b' {
|
||||
out.push(c);
|
||||
continue;
|
||||
}
|
||||
|
||||
// A CSI sequence is `\x1b[`, then parameter bytes, closed by a final byte in
|
||||
// `@` to `~`. That is every sequence `Color` writes. Anything else is a short
|
||||
// escape whose one following character goes with it, which `next` has taken.
|
||||
if chars.next() == Some('[') {
|
||||
for c in chars.by_ref() {
|
||||
if ('\x40'..='\x7e').contains(&c) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
out
|
||||
}
|
||||
|
||||
/// A destination for a command's output, chosen by the caller.
|
||||
///
|
||||
/// `main` hands a handler its own stdout and nothing about the CLI changes; the
|
||||
@@ -332,7 +368,10 @@ impl<'a> Sink<'a> {
|
||||
|
||||
/// An in-memory buffer, plain, for a test or a caller that colours the text
|
||||
/// itself.
|
||||
#[allow(dead_code)]
|
||||
///
|
||||
/// What the board's command prompt passes: the handler's words come back as text
|
||||
/// and the board styles them with ratatui, which is also why it must not be handed
|
||||
/// a coloured one — a paragraph prints an escape rather than obeying it.
|
||||
pub fn buffer(target: &'a mut Vec<u8>) -> Sink<'a> {
|
||||
Sink {
|
||||
writer: Box::new(target),
|
||||
@@ -1569,6 +1608,16 @@ pub fn parse_tags(content: &str) -> Vec<String> {
|
||||
return Vec::new();
|
||||
}
|
||||
|
||||
split_tags(&value)
|
||||
}
|
||||
|
||||
/// The tags in one comma-separated value, trimmed and without the empty ones.
|
||||
///
|
||||
/// Split out of [`parse_tags`] because a value typed on the command line is separated the
|
||||
/// same way the stored field is: `append --tags "bug, tui"` names two tags, and merging
|
||||
/// that into what a ticket already carries has to see two or it stores the pair as one
|
||||
/// tag and adds it again on the next call.
|
||||
pub fn split_tags(value: &str) -> Vec<String> {
|
||||
value
|
||||
.split(',')
|
||||
.map(str::trim)
|
||||
|
||||
@@ -68,6 +68,232 @@ fn fish_is_offered_every_status() {
|
||||
assert!(out.contains("-a 'backlog committed reviewing done discarded' -d status"));
|
||||
}
|
||||
|
||||
/// A board holding one ticket and one tag, for the rules whose values come off a board.
|
||||
///
|
||||
/// Returned with the ticket's id and the tag, since the assertions are that those exact
|
||||
/// strings are what fish offers.
|
||||
fn board() -> (assert_fs::TempDir, String, String) {
|
||||
let temp = assert_fs::TempDir::new().unwrap();
|
||||
let mut init = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
init.current_dir(temp.path()).arg("init").assert().success();
|
||||
|
||||
let mut add = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
add.current_dir(temp.path())
|
||||
.args(["add", "--title", "A ticket to complete", "--tags", "atag"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let mut ls = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let listed = ls
|
||||
.current_dir(temp.path())
|
||||
.args(["ls", "--ids"])
|
||||
.assert()
|
||||
.success();
|
||||
let listed = String::from_utf8(listed.get_output().stdout.clone()).unwrap();
|
||||
let id = listed.split('\t').next().unwrap().trim().to_string();
|
||||
|
||||
(temp, id, "atag".to_string())
|
||||
}
|
||||
|
||||
/// What fish would actually offer for a half-typed line, or `None` when fish is absent.
|
||||
///
|
||||
/// `complete -C` is fish's own answer to "what are the candidates here", so this asks the
|
||||
/// question a person at a prompt asks rather than searching the script for the rule that
|
||||
/// ought to produce the answer. Each candidate is a name and, after a tab, its description.
|
||||
///
|
||||
/// **The shell is pointed at the binary under test and stood in a real board**, which is
|
||||
/// what makes the dynamic half testable at all: its rules are command substitutions calling
|
||||
/// `worklane ls --ids` and `worklane tags`, so with no board and no binary they return
|
||||
/// nothing and every assertion about them would pass on an empty answer. The directory of
|
||||
/// `CARGO_BIN_EXE_worklane` goes on the front of PATH so the substitution runs this build
|
||||
/// rather than whatever is installed.
|
||||
///
|
||||
/// **`fish_complete_path` is emptied first, and without that line this test cannot fail.**
|
||||
/// `complete -C` autoloads completions for the command it is asked about, so a developer
|
||||
/// who has ever run `worklane completions fish > ~/.config/fish/completions/worklane.fish`
|
||||
/// gets that file merged into the answer. It was written by some earlier version of this
|
||||
/// binary and answers for whatever the rules used to be: the first draft of this test
|
||||
/// passed against a deliberately broken scope because the installed copy still had the
|
||||
/// working one. Emptying the path is what makes the sourced script the only source.
|
||||
fn candidates(board: &assert_fs::TempDir, line: &str) -> Option<Vec<String>> {
|
||||
// Beside the board rather than in it: a rule that fires nothing falls back to listing
|
||||
// the directory, and a script sitting in there would appear among the candidates and
|
||||
// read like an answer.
|
||||
let holder = assert_fs::TempDir::new().unwrap();
|
||||
let path = holder.path().join("worklane.fish");
|
||||
std::fs::write(&path, script("fish")).unwrap();
|
||||
|
||||
let bin_dir = std::path::Path::new(BIN_NAME).parent().unwrap();
|
||||
let inherited = std::env::var("PATH").unwrap_or_default();
|
||||
|
||||
let asked = std::process::Command::new("fish")
|
||||
.current_dir(board.path())
|
||||
.env("PATH", format!("{}:{inherited}", bin_dir.display()))
|
||||
.arg("-c")
|
||||
.arg(format!(
|
||||
"set fish_complete_path; source {}; complete -C '{line}'",
|
||||
path.display()
|
||||
))
|
||||
.output();
|
||||
|
||||
match asked {
|
||||
Ok(out) => Some(
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
.lines()
|
||||
.map(str::to_string)
|
||||
.collect(),
|
||||
),
|
||||
Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
|
||||
Err(err) => panic!("could not run fish: {err}"),
|
||||
}
|
||||
}
|
||||
|
||||
/// The name half of a candidate, dropping the description fish takes after the tab.
|
||||
fn names(candidates: &[String]) -> Vec<&str> {
|
||||
candidates
|
||||
.iter()
|
||||
.map(|line| line.split('\t').next().unwrap_or(line))
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// **Ask fish what it offers, instead of asserting that the rule that should make it
|
||||
/// offer that is in the file.**
|
||||
///
|
||||
/// Every other test here reads the script as text, which cannot tell a rule that fires
|
||||
/// from one whose condition stopped matching. That is how a completion actually breaks:
|
||||
/// the clap definition moves, a list or a `__worklane_command_is` scope no longer names
|
||||
/// anything, and the rule sits in the file offering nothing. Loading it into a real fish
|
||||
/// and asking for the candidates is the only check that can see the difference.
|
||||
///
|
||||
/// **Asserting the values, not only the names, is the point.** clap emits every option's
|
||||
/// name on its own, so `--tags` and `--blocked-by` are offered whether or not the dynamic
|
||||
/// half loaded: an assertion that they appear passes with every hand-written rule deleted.
|
||||
/// What those rules add is the candidates *after* the flag, and that is what is pinned
|
||||
/// here, against the board `board()` puts under the shell.
|
||||
///
|
||||
/// Descriptions are read off deliberately and not asserted: every option carrying a
|
||||
/// hand-written rule currently loses the help text clap gave it, which is its own ticket
|
||||
/// rather than something to pin as correct here.
|
||||
///
|
||||
/// **Skipped when fish is not on PATH, and it says so.** There is no CI here and fish is
|
||||
/// the shell this tool is written for, so failing a machine that never had it would be a
|
||||
/// guard nobody could satisfy. A missing fish means the check did not run, not that it
|
||||
/// passed.
|
||||
#[test]
|
||||
fn fish_offers_the_commands_the_statuses_and_the_values() {
|
||||
let (temp, id, tag) = board();
|
||||
|
||||
let Some(commands) = candidates(&temp, "worklane ") else {
|
||||
eprintln!("skipped: fish is not on PATH, so nothing asked it for candidates");
|
||||
return;
|
||||
};
|
||||
for command in [
|
||||
"add", "ls", "show", "mv", "set", "append", "relate", "campaign",
|
||||
] {
|
||||
assert!(
|
||||
names(&commands).contains(&command),
|
||||
"`worklane <TAB>` never offers {command}"
|
||||
);
|
||||
}
|
||||
|
||||
// The `ls` status positional, which clap emits nothing for, so this answer comes from
|
||||
// the dynamic half alone and an empty one means that half stopped loading.
|
||||
let statuses = candidates(&temp, "worklane ls ").unwrap();
|
||||
for status in ["backlog", "committed", "reviewing", "done", "discarded"] {
|
||||
assert!(
|
||||
names(&statuses).contains(&status),
|
||||
"`worklane ls <TAB>` never offers {status}"
|
||||
);
|
||||
}
|
||||
|
||||
let shells = candidates(&temp, "worklane completions ").unwrap();
|
||||
for shell in ["fish", "bash", "zsh"] {
|
||||
assert!(
|
||||
names(&shells).contains(&shell),
|
||||
"`worklane completions <TAB>` never offers {shell}"
|
||||
);
|
||||
}
|
||||
|
||||
// Every rule whose values come off the board, one per list it is generated from.
|
||||
let ticket_value = [
|
||||
("worklane show ", "TICKET_COMMANDS"),
|
||||
("worklane chown alice ", "TICKET_SECOND_COMMANDS"),
|
||||
("worklane relate --blocked-by ", "TICKET_FLAGS"),
|
||||
("worklane chown --clear ", "the chown --clear rule"),
|
||||
];
|
||||
for (line, list) in ticket_value {
|
||||
let offered = candidates(&temp, line).unwrap();
|
||||
assert!(
|
||||
names(&offered).contains(&id.as_str()),
|
||||
"`{line}<TAB>` never offers the one ticket on the board, so {list} is not reaching it: {offered:?}"
|
||||
);
|
||||
}
|
||||
|
||||
let tag_value = [
|
||||
("worklane ls --tag ", "TAG_FLAGS"),
|
||||
("worklane append --tags ", "TAG_FLAGS"),
|
||||
("worklane tags set ", "TAG_NESTED_COMMANDS"),
|
||||
];
|
||||
for (line, list) in tag_value {
|
||||
let offered = candidates(&temp, line).unwrap();
|
||||
assert!(
|
||||
names(&offered).contains(&tag.as_str()),
|
||||
"`{line}<TAB>` never offers the one tag on the board, so {list} is not reaching it: {offered:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// **The script is handed to fish, which parses it without running it.**
|
||||
///
|
||||
/// The fish half is a hand-written `format!` string carrying single quotes, command
|
||||
/// substitutions and backslash line continuations, and every text assertion in this file
|
||||
/// is a `contains`, which a broken script satisfies exactly as well as a correct one.
|
||||
/// `--no-execute` is the parse without the run.
|
||||
///
|
||||
/// **What it catches is a script that does not parse**: quotes still open at the end of
|
||||
/// the file, an unclosed block. That is narrower than it sounds and the limit is worth
|
||||
/// writing down, because it was measured rather than assumed. An apostrophe interpolated
|
||||
/// into a `-d` description partway down the file re-balances against the next quote and
|
||||
/// parses, corrupting every rule in between while this test passes; the same apostrophe in
|
||||
/// the *last* rule reaches the end unbalanced and is caught. So this is a floor, not an
|
||||
/// oracle, and `fish_offers_the_commands_the_statuses_and_the_flags` is the one that reads
|
||||
/// what the rules actually do.
|
||||
///
|
||||
/// Only fish, because only fish gets a hand-written half. What the other four shells are
|
||||
/// given is clap's output whole, which `no_other_shell_gets_the_fish_half` pins, so a
|
||||
/// syntax error there would be clap's bug and not this repo's to catch.
|
||||
///
|
||||
/// **Skipped when fish is not on PATH, and it says so.** The trade is deliberate: there is
|
||||
/// no CI here and fish is the shell this tool is written for, so failing a machine that
|
||||
/// never had it would be a guard nobody could satisfy. A missing fish means the check did
|
||||
/// not run, not that it passed.
|
||||
#[test]
|
||||
fn fish_parses_the_script_it_is_given() {
|
||||
let temp = assert_fs::TempDir::new().unwrap();
|
||||
let path = temp.path().join("worklane.fish");
|
||||
std::fs::write(&path, script("fish")).unwrap();
|
||||
|
||||
let parsed = std::process::Command::new("fish")
|
||||
.arg("--no-execute")
|
||||
.arg(&path)
|
||||
.output();
|
||||
|
||||
let out = match parsed {
|
||||
Ok(out) => out,
|
||||
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
|
||||
eprintln!("skipped: fish is not on PATH, so the generated script went unparsed");
|
||||
return;
|
||||
}
|
||||
Err(err) => panic!("could not run fish: {err}"),
|
||||
};
|
||||
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"fish refuses the script `worklane completions fish` writes:\n{}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_unknown_shell_is_a_usage_error() {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
|
||||
@@ -676,6 +676,140 @@ fn append_requires_at_least_one_section() {
|
||||
assert_eq!(run(&temp, &["append", UUID]).status.code(), Some(2));
|
||||
}
|
||||
|
||||
/// The reason the flag exists: `set --tags` writes the whole field, so adding one tag to
|
||||
/// a ticket that already carries some meant knowing and retyping every one of them.
|
||||
#[test]
|
||||
fn append_adds_a_tag_and_keeps_the_ones_already_there() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["append", UUID, "--tags", "beta"]);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
let content = ticket(&worklane);
|
||||
assert!(content.contains("- **Tags**: alpha, beta"), "{content}");
|
||||
// The sections and the other fields are as untouched as they are by any other append
|
||||
assert!(content.contains("- [x] Crit one\n- [ ] Crit two\n"), "{content}");
|
||||
assert!(content.contains("- **Priority**: 3"), "{content}");
|
||||
}
|
||||
|
||||
/// Idempotent on purpose: the caller of an append does not have to know what is there
|
||||
/// already, so naming a tag the ticket carries is reported as no change and writes
|
||||
/// nothing, the way an unchanged field is everywhere else.
|
||||
#[test]
|
||||
fn append_ignores_a_tag_the_ticket_already_carries() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &["append", UUID, "--tags", "alpha"]);
|
||||
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
|
||||
assert!(
|
||||
String::from_utf8_lossy(&out.stdout).contains("No changes to"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
);
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
|
||||
// And the one already there is not added a second time beside a new one
|
||||
run(&temp, &["append", UUID, "--tags", "alpha", "--tags", "beta"]);
|
||||
assert!(
|
||||
ticket(&worklane).contains("- **Tags**: alpha, beta"),
|
||||
"{}",
|
||||
ticket(&worklane)
|
||||
);
|
||||
}
|
||||
|
||||
/// Two spellings for the same call, because the stored field is comma separated too and
|
||||
/// `set --tags` takes that form on this very field: refusing it on the counterpart would
|
||||
/// be a trap. New tags land in the order they were given, after the ones already there.
|
||||
#[test]
|
||||
fn append_takes_several_tags_by_repeated_flag_or_by_comma() {
|
||||
for args in [
|
||||
vec!["append", UUID, "--tags", "bug", "--tags", "tui"],
|
||||
vec!["append", UUID, "--tags", "bug, tui"],
|
||||
vec!["append", UUID, "-g", "bug,tui"],
|
||||
] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
|
||||
let out = run(&temp, &args);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"{args:?}: {:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
assert!(ticket(&worklane).contains("- **Tags**: alpha, bug, tui"), "{args:?}");
|
||||
}
|
||||
}
|
||||
|
||||
/// A value that names no tag is refused rather than written, the way an all-blank section
|
||||
/// value is: `--tags ","` adds nothing, and writing the field back unchanged would report
|
||||
/// an append that never happened. Emptying the field is `set --clear tags`.
|
||||
#[test]
|
||||
fn append_refuses_a_tags_value_that_names_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane);
|
||||
let before = ticket(&worklane);
|
||||
|
||||
// Empty at the parser, before the ticket is even resolved
|
||||
let empty = run(&temp, &["append", UUID, "--tags", ""]);
|
||||
assert_eq!(empty.status.code(), Some(2));
|
||||
assert!(
|
||||
String::from_utf8_lossy(&empty.stderr).contains("value cannot be empty"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&empty.stderr)
|
||||
);
|
||||
// The message must not name a `--clear` this command does not have
|
||||
assert!(
|
||||
!String::from_utf8_lossy(&empty.stderr).contains("use --clear"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&empty.stderr)
|
||||
);
|
||||
|
||||
// Separators only, which the parser cannot see is empty
|
||||
let blank = run(&temp, &["append", UUID, "--tags", ", ,"]);
|
||||
assert_eq!(blank.status.code(), Some(1));
|
||||
assert!(
|
||||
String::from_utf8_lossy(&blank.stderr).contains("Nothing to append to the tags"),
|
||||
"{:?}",
|
||||
String::from_utf8_lossy(&blank.stderr)
|
||||
);
|
||||
|
||||
assert_eq!(ticket(&worklane), before);
|
||||
}
|
||||
|
||||
/// A ticket with no tags starts the list rather than appending to the sentinel.
|
||||
#[test]
|
||||
fn append_writes_the_first_tag_over_the_unset_sentinel() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let mut add = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
add.current_dir(temp.path())
|
||||
.args(["add", "--title", "Untagged"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let uuid = fs::read_dir(worklane.join("backlog"))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.next()
|
||||
.map(|name| name.split('_').next().unwrap().to_string())
|
||||
.unwrap();
|
||||
|
||||
run(&temp, &["append", &uuid, "--tags", "bug"]);
|
||||
|
||||
let content = ticket(&worklane);
|
||||
assert!(content.contains("- **Tags**: bug"), "{content}");
|
||||
assert!(!content.contains("_None_"), "{content}");
|
||||
}
|
||||
|
||||
/// Owner belongs to chown and status to mv, so neither command offers them.
|
||||
#[test]
|
||||
fn neither_command_can_write_owner_or_status() {
|
||||
|
||||
+45
-3
@@ -275,6 +275,36 @@ fn clearing_the_tags_writes_a_tags_entry() {
|
||||
assert!(entry.starts_with("**Tags**\nalpha → _None_\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// Tags are logged wherever they change, so the command that adds to them logs the same
|
||||
/// entry the one that replaces them does. The values come off the field rather than off
|
||||
/// the flag, so the entry records where the field went and not what the call added: an
|
||||
/// append of `beta` onto `alpha` reads as the pair, not as `beta`.
|
||||
#[test]
|
||||
fn appending_a_tag_writes_a_tags_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["append", UUID, "--tags", "beta"]);
|
||||
|
||||
let entry = only_entry(&worklane, "tags");
|
||||
assert!(entry.starts_with("**Tags**\nalpha → alpha, beta\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// The sections are not logged, and appending to one is not a tag change: an append that
|
||||
/// touches no tag writes nothing, so the log does not fill with the edits it deliberately
|
||||
/// leaves out.
|
||||
#[test]
|
||||
fn appending_to_a_section_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["append", UUID, "--acceptance", "One more criterion"]);
|
||||
|
||||
assert_eq!(entries(&worklane), vec![]);
|
||||
}
|
||||
|
||||
/// The entry names the campaign the way a reader knows it, the codename, not the uuid
|
||||
/// the field actually holds. A ticket never assigned starts from the sentinel an unset
|
||||
/// field reads as everywhere else.
|
||||
@@ -433,6 +463,7 @@ fn a_no_op_edit_writes_nothing() {
|
||||
vec!["mv", UUID, "--status", "backlog"],
|
||||
vec!["chown", "alice", UUID],
|
||||
vec!["set", UUID, "--tags", "alpha"],
|
||||
vec!["append", UUID, "--tags", "alpha"],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert!(
|
||||
@@ -577,10 +608,11 @@ fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() {
|
||||
run(&temp, &["mv", UUID, "--status", "committed", "--actor", "opencode"]);
|
||||
run(&temp, &["chown", "bob", UUID, "--actor", "opencode"]);
|
||||
run(&temp, &["set", UUID, "--tags", "beta", "--actor", "opencode"]);
|
||||
run(&temp, &["append", UUID, "--tags", "gamma", "--actor", "opencode"]);
|
||||
run(&temp, &["assign", "v1", UUID, "--actor", "opencode"]);
|
||||
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 5, "{found:?}");
|
||||
assert_eq!(found.len(), 6, "{found:?}");
|
||||
for (name, content) in found {
|
||||
assert!(content.contains("**Author**: opencode"), "{name}: {content:?}");
|
||||
}
|
||||
@@ -609,10 +641,11 @@ fn actor_from_git_names_the_git_user_on_every_command_that_writes_one() {
|
||||
run_for_the_human(&temp, &["mv", UUID, "--status", "committed", "--actor-from-git"]);
|
||||
run_for_the_human(&temp, &["chown", "bob", UUID, "--actor-from-git"]);
|
||||
run_for_the_human(&temp, &["set", UUID, "--tags", "beta", "--actor-from-git"]);
|
||||
run_for_the_human(&temp, &["append", UUID, "--tags", "gamma", "--actor-from-git"]);
|
||||
run_for_the_human(&temp, &["assign", "v1", UUID, "--actor-from-git"]);
|
||||
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 5, "{found:?}");
|
||||
assert_eq!(found.len(), 6, "{found:?}");
|
||||
for (name, content) in found {
|
||||
assert!(content.contains("**Author**: Ansho Rei"), "{name}: {content:?}");
|
||||
}
|
||||
@@ -627,7 +660,7 @@ fn actor_and_actor_from_git_are_refused_together() {
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
let calls: [&[&str]; 5] = [
|
||||
let calls: [&[&str]; 6] = [
|
||||
&[
|
||||
"comment",
|
||||
UUID,
|
||||
@@ -662,6 +695,15 @@ fn actor_and_actor_from_git_are_refused_together() {
|
||||
"opencode",
|
||||
"--actor-from-git",
|
||||
],
|
||||
&[
|
||||
"append",
|
||||
UUID,
|
||||
"--tags",
|
||||
"beta",
|
||||
"--actor",
|
||||
"opencode",
|
||||
"--actor-from-git",
|
||||
],
|
||||
&[
|
||||
"assign",
|
||||
"v1",
|
||||
|
||||
Reference in New Issue
Block a user