Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
108e21ad7f | ||
|
|
26b93f8f53 | ||
|
|
7126138d46 | ||
|
|
3592584747 | ||
|
|
5dc087d49e | ||
|
|
07c783410c | ||
|
|
dd2b457bff | ||
|
|
af1ef1f97f | ||
|
|
8e2ab6332c |
@@ -13,6 +13,7 @@
|
||||
- `assets/SKILL.md` - the agent skill for the CLI itself, embedded with `include_str!`
|
||||
- `assets/REVIEW.md` - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; `SKILL.md` keeps its name because the role it teaches is the CLI
|
||||
- `assets/PLAN.md` - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns
|
||||
- `assets/ADMIN.md` - the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line against `PLAN.md` in both directions: this one decides the vocabulary, that one applies it
|
||||
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
|
||||
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command
|
||||
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs`
|
||||
@@ -44,6 +45,10 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Tests use `assert_cmd` and `assert_fs` for CLI testing
|
||||
- `setup_worklane()` creates temp `.worklane/` with all four 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
|
||||
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
|
||||
- **Every unit-test fixture directory goes through `util::Fixture`, and nothing calls `remove_dir_all` at the end of a test.** `Fixture::new(prefix)` makes a uuid-named directory under the system temp dir and its `Drop` removes it, which is the only shape that also runs when an assertion fails — a trailing line does not, and a failing test is exactly when a fixture is most likely to be stranded. That was b74dc5a: `/tmp` reached 18363 of these and filled the disk, failing a link step and then a `git add` with "No space left on device", an error naming neither the tests nor what they left behind
|
||||
- **`Fixture` derefs to `Path` and also implements `AsRef<Path>`**, because the two reach different call sites: a parameter typed `&Path` is a coercion site and one bound by `impl AsRef<Path>` is not. `Fixture::child(name)` points the fixture at a directory inside itself while still removing the parent, which is the tree `project_tree` needs. The prefix earns its place on the one path that is ever left behind, which is why this is a small guard rather than `assert_fs::TempDir` — that names its directories `.tmpXXXXXX`, which says nothing about whose they are
|
||||
- **`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:
|
||||
@@ -120,6 +125,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
|
||||
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description
|
||||
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does
|
||||
- **A call whose values are *every one* blank is refused, by `replaced_items` for `set` and `appended_items` for `append`.** The check is the section's rather than the object's, so `campaign set --description` shares it. What differs is the way out, which is why `replaced_items` takes it as an argument: a ticket's section is emptied with `--clear <field>` and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two
|
||||
|
||||
### Clearing a Field
|
||||
- **`set --clear <field>` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes
|
||||
@@ -180,9 +186,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `campaign ls` scans the status directories **once per campaign** to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice
|
||||
- **The TUI got a card label and a frame, not a campaign tab.** 61879a4 decided it. A tab would have had to answer what its columns are, and a campaign groups *across* the flow rather than within one status, so the honest answer is the four statuses filtered — which is a filter on the board it already has rather than a fifth tab. So: a label on the card, a frame above the columns while one is selected, and `c` for the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project in `columns_of` and is what names the label; see The Board View
|
||||
- **A campaign is named by its codename on the board, and by its short id when it has none.** The uuid does not fit on a card and the title is a sentence, which is the gap `Codename` fills. `campaign_label` builds it in one place, as a `Cell`, so the CLI paints it and the board makes a span of it; the mark is `CAMPAIGN_MARK`, `~`, beside `#` for a tag
|
||||
- **`campaign set` is the only writer of a filed campaign's fields, and it carries the two scalars.** d637288 decided it: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `--title`, which renames the file the way `set --title` does, and `--codename`. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
|
||||
- **`campaign set` and `campaign append` are the only writers of a filed campaign's fields.** d637288 decided the command: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `set` carries `--title`, which renames the file the way `set --title` does, `--description` and `--codename`; `append` carries `--description` alone. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
|
||||
- **Replacing a codename the campaign already has needs `--force`.** Once a campaign has one it is referred to by it: it is on every card in the campaign, it is what resolves the campaign at the command line, and it is in somebody's shell history. Changing it silently is the mistake `install-skill --force` exists to prevent, so it is refused and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like `SetArgs::contested`, so a call also carrying `--title` writes neither field. Setting the codename a campaign already carries stays a **no-op, not a refusal** — `--force` is about overwriting a *different* word, which is the same division `install::Outcome` draws between `Unchanged` and `Refused`. `--force` guards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required
|
||||
- **No `campaign set --description`, and that is the line, not an oversight.** `set` and `append` are a pair for a prose section: a way to replace a description with no way to add a paragraph is half of it. The two scalars have no append form at all, which is the same line `append` already draws for a ticket. `campaign_set_offers_no_description_and_no_owner` pins it. No `--owner` either, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign; and no `--clear`, because a wrong codename is replaced rather than emptied and `Clearable` is `SetArgs`'s, its variants being a ticket's fields
|
||||
- **The description arrived as a pair, `set --description` and `campaign append`, 32e98ab.** Never one without the other: for a prose section `set` replaces and `append` adds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same line `append` already draws for a ticket, and `campaign_append_offers_only_the_description` pins that. Neither flag takes `--force`: a description is prose written to be revised, the same reason `tags set --annotation` has none
|
||||
- **`append` is a campaign's own subcommand, not the top-level `append`.** That one resolves a ticket, and one positional naming either object is the ambiguity `resolve_in` makes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar of `resolve_ticket`, which explains a ticket search that *names* a campaign. Under `campaign` the object is settled by the command, as it is for `set`, `show` and `ls`
|
||||
- **Still no `--owner` and still no `--clear`.** No `--owner`, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign. No `--clear`, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would be `Clearable` on a campaign, whose variants are a ticket's fields, or a second enum with one variant in it. `campaign_set_offers_no_owner_and_no_clear` pins both
|
||||
- **An empty `--description ""` is a paragraph break here too, and the refusal for an all-blank value names no flag.** Every prose argument in the tool reads a blank value that way, `add`, `set` and `tags --annotation` alike, so a campaign reading it as *empty the section* would be the one exception. With no `--clear` to point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist. `replaced_items` is where the check lives, shared with `set`, and the way out is the caller's argument for exactly that reason
|
||||
- **`SECTION_ORDER` needs no campaign variant, and that is what the one-section file proves.** A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, *filtered by what is actually in the file*, so a campaign's description anchors against `## Metadata` — which is where `campaign_body` writes it. `the_description_is_edited_in_place_in_a_file_with_one_section` pins that no section a campaign does not have gets inserted to anchor against
|
||||
- **A campaign whose Description heading is gone is refused, not given the section back.** No `ensure_section` on this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, where `add` writes nothing and the insertion is the only path there is. The refusal therefore names the section and **not** the object — "There is no description section to write to" — because both a ticket and a campaign reach `replace_section_body` now. `write_then_replace` still carries the noun, where the message is about a file
|
||||
- **The codename is written through `set_or_insert_metadata_field`, not `set_metadata_field`.** Every campaign filed before the field existed has no such line, and those are exactly the campaigns the command is for, which is the same reasoning that puts `assign` on the upsert. **`Codename` is therefore in `METADATA_ORDER`, directly after ID**, so an inserted one lands where `campaign_body` writes it and a campaign given a codename later is the same file as one filed with it. Nothing upserts it on a ticket, so its place in a ticket's order costs nothing
|
||||
- **One write path for tickets and campaigns.** `save_entry` is the body, `save_ticket` and `save_campaign` are the named wrappers, and `write_then_replace` and `find_entry_file` take the noun as a `&str` so a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here, `<uuid>_<slug>.md` in a directory, and the rename happens only after the write has landed. Every message puts the noun mid-sentence so there is no capital to case
|
||||
- `campaign_body()` builds the file from `DESCRIPTION` and `METADATA_HEADING` rather than its own string literals, so the two file formats cannot drift apart on the spelling of a heading. A campaign has no acceptance criteria (its definition of done is derived), no implementation plan and no Status
|
||||
@@ -198,6 +209,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `notify` is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387
|
||||
- Cards come from `collect_ticket_items`, the same source `ls` uses, so there is no second parser. `TicketItem::path` exists for the detail view
|
||||
- **The detail view scrolls on `pgup` and `pgdn`, not on up and down.** Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them
|
||||
- **The campaign frame scrolls on the same two keys, and `Board::scroll_page` is where the precedence lives.** An open ticket wins, whatever holds the selection behind it; the frame takes them only when there is no overlay to take them first. In `Board` rather than in the `main.rs` arm for the reason `dismiss` is: a layering rule written into that dispatch is a rule nothing can check
|
||||
- The scroll offset is clamped against the *wrapped* line count, from `Paragraph::line_count`, which is why `ratatui` carries the `unstable-rendered-line-info` feature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed
|
||||
- The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
|
||||
- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does *not* reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
|
||||
@@ -233,11 +245,23 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
|
||||
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the four statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `done_count` and the copy key all keep working unchanged
|
||||
- **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
|
||||
- **The frame above the columns is three rows, and `Chrome` is what every measurement takes.** `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
|
||||
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` on the bottom left. One text row, the opening line of the description. Every row spent here is a row of cards
|
||||
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::campaign` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign, because both heights have to be measured the same way by everything that measures the board. `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
|
||||
- **The whole description is carried off the one read, and the cut is on the view.** `section_prose` replaced `section_opening`, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and `CampaignRow::summary` takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file
|
||||
- **`CAMPAIGN_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
|
||||
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::campaign_rows` takes the height because of this, and `frame_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
|
||||
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `CAMPAIGN_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
|
||||
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
|
||||
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with a campaign selected the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
|
||||
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no campaign is selected is the one state that must never exist — `select_campaign` and `reload` are what keep it from arising
|
||||
- **`Tab::selected` hands back nothing while the frame holds the selection.** Every key that acts on a card has to answer for the frame. `←→` are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. `y` is the exception that earns its place: it copies the campaign's short id, so `y copy id` means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about
|
||||
- **`enter` routes on the focus through `Board::toggle_focused`: the frame's height on the frame, the overlay on a card.** It used to be inert on the frame for free, because `Tab::selected` hands back nothing and `toggle_detail` therefore had nothing to open. That is no longer an answer, and the routing is in `Board` rather than in the `main.rs` arm for the reason `dismiss` and `scroll_page` are
|
||||
- **`q` does not gain a layer for the expanded frame, and up and down do not take it back.** The expanded frame is the frame at its other height, not a thing laid over the board, so `q` goes on taking the campaign filter off from either height and `enter` is the only key that undoes what `enter` did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. `Tab::expanded` sits beside the filter and resets where `select_campaign` and `reload` reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
|
||||
- **The toggle re-clamps the frame offset, through `scroll_frame(0, screen)`.** A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the next `pgup` counts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives
|
||||
- **The frame is out of reach from under an open ticket.** With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. `an_open_ticket_keeps_the_scroll_keys_from_the_frame` builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it
|
||||
- **The standing comes from the columns, not from a walk of the tree.** While a campaign is selected the columns *are* its members, done included, so `Tab::standing` counts what is already in hand rather than paying what `campaign ls` pays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted
|
||||
- **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows
|
||||
- **`c` is named in the footer only on a closed board with nothing selected**, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
|
||||
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `enter expand` or `enter collapse`, the two scroll keys and `y copy id`, and leaves out `←→` because they do nothing there. It has to say which way `enter` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
|
||||
- **`picker: Option<Picker>` is the whole mode**, the shape `search` and `detail` use, and `Board::picker_key` runs beside `search_key` ahead of the action arms for the same reason: an open list owns the keyboard, so `d` must not toggle done and `q` must not quit while a campaign is being chosen. `ctrl-c` is the one key it declines and every other control combination is swallowed, or `ctrl-d` would reach the arm bound to `d`
|
||||
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
|
||||
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
|
||||
@@ -374,7 +398,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
### Color and Output
|
||||
- Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in
|
||||
- **`color_text()` is for the CLI's own printing only. Anything reachable from `content_trim` takes the decision as an argument and calls `paint()`**, because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes. `nothing_the_body_renders_asks_the_terminal_for_the_colour_decision` scans this file and fails on a new caller; the allowlist is `ambiguous`, which builds a failed-search message for stderr
|
||||
- A function that takes an `enabled` flag must use it all the way down. `colorize_bold` honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function
|
||||
- A function that takes an `enabled` flag must use it all the way down. `colorize_inline` honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function
|
||||
- **A test that asserts an absence has to be paired with one that asserts the presence.** The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so `should_use_colors()` was false and the leaking branch was never taken. The pair is now `content_trim(.., false)` has no escape and `content_trim(.., true)` still colours, which pins the flag as the only thing that decides
|
||||
- **The palette is the `Color` enum, not a string.** `Color::ansi()` gives the CLI its SGR sequence and `From<Color> for ratatui::style::Color` gives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is how `magenta` came to be undefined
|
||||
- Reset color with `\x1b[0m` after colored text
|
||||
@@ -391,6 +415,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
|
||||
- Relation kind mark → brightred `×` blocked by and blocks, cyan `→` relates to, orange `←` regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking
|
||||
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `?` for a target the board does not hold. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
|
||||
- Markdown link → cyan, markers and url kept. Not a new meaning for the colour: the plan numbers, the criterion numbers and the `relates to` mark are already cyan inside a rendered body, and a link is the same kind of thing, a pointer the reader may follow rather than a value. The url is not hidden behind the text the way a renderer would hide it, because `show` prints to a terminal worklane cannot assume will make it clickable, and a link whose target cannot be read is worse than a long line
|
||||
- Chrome → grey. The footer's key names, a rendered `[ ]`, and the overlay's page indicator. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level
|
||||
- Campaign label → its codename through `tag_color`, bold, marked `~`. The colour is what groups a campaign across the cards that carry it, which is exactly what a tag's colour is for, and one word is one colour in every view because `tag_color` is a pure function of it. The mark and the bold are what tell it from a tag on a row that holds both: the mark is not `#`, or the row would read as a list of tags with a stranger in it, and not `@`, which reads as a person on every board anyone has used. `Codename` in a metadata table takes the colour without the mark, since the field name has already said what it is
|
||||
- Campaign label with no codename → grey. The label is then the short id, and grey keeps a reserved meaning off a `TAG_COLORS` slot in the one case where it would land on one: red is the uuid's everywhere else, and grey already means what a reader skips, which is what a campaign with no codename has to say for itself
|
||||
@@ -402,7 +427,8 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. `\x1b[38;5;8m` is byte for byte what crossterm emits for ratatui's `Color::DarkGray`, the grey frig and pantop use for dimmed rows
|
||||
|
||||
### Code Organization
|
||||
- Colorization functions (`colorize_ordered`, `colorize_bold`, `content_trim_colored`) handle markdown formatting. `colorize_line` is gone: it was a `pub` alias for `colorize_bold` with one caller, and the only thing it added was asking the terminal
|
||||
- Colorization functions (`colorize_ordered`, `colorize_inline`, `content_trim_colored`) handle markdown formatting. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
|
||||
- **`colorize_inline` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
|
||||
- `show` renders the Metadata section as a two column table via `render_metadata_table`, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
|
||||
- The title is printed once, by `cmd_show`. `content_trim_colored` skips the `# ` heading in the file content
|
||||
- Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
|
||||
@@ -430,12 +456,12 @@ and this file is for what someone changing worklane's own code needs.
|
||||
### Version Bumps
|
||||
- Before every commit, decide whether the change warrants a version bump in `Cargo.toml`
|
||||
- Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
|
||||
- **`make patch`, `make minor` and `make major` do the mechanics**, run after the commit is in: each bumps `Cargo.toml` and the `worklane` entry in `Cargo.lock`, appends `, and bump to <version>` to the commit's subject, folds the bump into that commit, and tags it. Bumping by hand is how a version comes to be left untagged, which is what the one action is for. It refuses on a dirty tree, on an already-tagged `HEAD` and on a `HEAD` that is already pushed, since each of those makes the amend lose work, orphan a tag or need a force push
|
||||
- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
|
||||
- **Changed output means the CLI's output.** That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
|
||||
- **Settling output that shipped one version ago is a patch**, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features
|
||||
- No bump for docs-only, tests-only or `--fixup` commits
|
||||
- When one body of work spans several commits, bump once on the final commit rather than on each
|
||||
- Bump `Cargo.toml` and the `worklane` entry in `Cargo.lock` together, in the commit that carries the bump
|
||||
- Every bump gets a matching annotated tag, `v<version>`, on the bump commit — a bumped version is never left untagged
|
||||
- Tag locally only; never push a tag unless asked
|
||||
- `worklane --version` reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another
|
||||
|
||||
Generated
+1
-1
@@ -1503,7 +1503,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.26.0"
|
||||
version = "0.27.2"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.26.0"
|
||||
version = "0.27.2"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
# Release helpers.
|
||||
#
|
||||
# `make patch|minor|major` bumps the version in Cargo.toml and Cargo.lock, folds
|
||||
# that bump into the last commit, and tags it. Everything is one action so a
|
||||
# release cannot end up half-done: no version bump left untagged, no tag without
|
||||
# a bump.
|
||||
|
||||
.PHONY: help patch minor major version release install
|
||||
|
||||
help:
|
||||
@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"
|
||||
|
||||
# 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.
|
||||
PACKAGE = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^name *= *"/{print $$2; exit}' Cargo.toml)
|
||||
CURRENT = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^version *= *"/{print $$2; exit}' Cargo.toml)
|
||||
|
||||
# 1 appends ", and bump to <version>" to the amended commit's subject; empty
|
||||
# leaves the message alone.
|
||||
AMEND_SUBJECT = 1
|
||||
|
||||
version:
|
||||
@echo $(CURRENT)
|
||||
|
||||
patch: BUMP = patch
|
||||
minor: BUMP = minor
|
||||
major: BUMP = major
|
||||
patch minor major: release
|
||||
|
||||
# A release rewrites the last commit, so refuse anything that would make that
|
||||
# rewrite lose work or orphan a tag.
|
||||
release:
|
||||
@set -e; \
|
||||
if ! git rev-parse -q --verify HEAD >/dev/null 2>&1; then \
|
||||
echo "error: no commits yet, so there is no commit to fold a version bump into. Commit first." >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
if [ -n "$$(git status --porcelain)" ]; then \
|
||||
echo "error: working tree is dirty. Commit or stash first, and decide whether that work belongs in this version:" >&2; \
|
||||
git status --short >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
if [ -n "$$(git tag --points-at HEAD)" ]; then \
|
||||
echo "error: HEAD is already tagged $$(git tag --points-at HEAD | paste -sd' '). Amending it would leave that tag on an orphaned commit. Commit something first." >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
if upstream=$$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null) && \
|
||||
git merge-base --is-ancestor HEAD "$$upstream" 2>/dev/null; then \
|
||||
echo "error: HEAD is already pushed to $$upstream. Amending it would need a force push. Commit something first." >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
current="$(CURRENT)"; \
|
||||
if [ -z "$$current" ]; then echo "error: no version found in the [package] table of Cargo.toml" >&2; exit 1; fi; \
|
||||
new=$$(echo "$$current" | awk -F. -v kind=$(BUMP) '{ \
|
||||
if (NF != 3) exit 1; \
|
||||
if (kind == "patch") printf "%d.%d.%d\n", $$1, $$2, $$3 + 1; \
|
||||
else if (kind == "minor") printf "%d.%d.0\n", $$1, $$2 + 1; \
|
||||
else printf "%d.0.0\n", $$1 + 1 }'); \
|
||||
if [ -z "$$new" ]; then echo "error: cannot bump version '$$current': expected major.minor.patch" >&2; exit 1; fi; \
|
||||
if git rev-parse -q --verify "refs/tags/v$$new" >/dev/null; then \
|
||||
echo "error: tag v$$new already exists" >&2; exit 1; \
|
||||
fi; \
|
||||
awk -v v="$$new" '/^\[package\]/{p=1} /^\[/ && !/^\[package\]/{p=0} p && /^version *= *"/{sub(/"[^"]*"/, "\"" v "\"")} {print}' Cargo.toml > Cargo.toml.bump; \
|
||||
mv Cargo.toml.bump Cargo.toml; \
|
||||
git add Cargo.toml; \
|
||||
if [ -f Cargo.lock ] && git ls-files --error-unmatch Cargo.lock >/dev/null 2>&1; then \
|
||||
awk -v v="$$new" -v pkg="$(PACKAGE)" '$$0 == "name = \"" pkg "\""{f=1} f && /^version = "/{sub(/"[^"]*"/, "\"" v "\""); f=0} {print}' Cargo.lock > Cargo.lock.bump; \
|
||||
mv Cargo.lock.bump Cargo.lock; \
|
||||
git add Cargo.lock; \
|
||||
fi; \
|
||||
if [ -n "$(AMEND_SUBJECT)" ]; then \
|
||||
subject=$$(git log -1 --format=%s | sed -E 's/, and bump to [0-9]+\.[0-9]+\.[0-9]+$$//'); \
|
||||
body=$$(git log -1 --format=%b); \
|
||||
if [ -n "$$body" ]; then \
|
||||
git commit --quiet --amend -m "$$subject, and bump to $$new" -m "$$body"; \
|
||||
else \
|
||||
git commit --quiet --amend -m "$$subject, and bump to $$new"; \
|
||||
fi; \
|
||||
else \
|
||||
git commit --quiet --amend --no-edit; \
|
||||
fi; \
|
||||
git tag -a "v$$new" -m "v$$new"; \
|
||||
echo "$$current -> $$new, tagged v$$new on $$(git rev-parse --short HEAD) ($$(git log -1 --format=%s))"
|
||||
|
||||
install:
|
||||
cargo install --path .
|
||||
worklane install-skill
|
||||
@@ -5,7 +5,7 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
## Commands
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, whose border carries a page indicator while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it and says how far it has got, and `q` on its border gives the whole board back. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
|
||||
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
|
||||
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories |
|
||||
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
|
||||
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
|
||||
@@ -19,13 +19,14 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
|
||||
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
|
||||
| `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by |
|
||||
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, and `--codename`. At least one required. The only way to change a campaign after it is filed, and the way a campaign filed before codenames existed gets one. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. No `--description`: replacing prose without an `append` to add a paragraph is half a pair |
|
||||
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` |
|
||||
| `worklane campaign append <campaign>` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket |
|
||||
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion |
|
||||
| `worklane campaign show <campaign>` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks |
|
||||
| `worklane assign <campaign> <ticket>` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it |
|
||||
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
|
||||
| `worklane completions <shell>` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below |
|
||||
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Three ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
|
||||
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Four ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns, and `worklane-admin` sets a board up and repairs one, its tag vocabulary and the faults a board can develop. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
|
||||
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
|
||||
|
||||
## Completions
|
||||
@@ -77,3 +78,20 @@ Whether a truncated pipe reports 141 or 0 depends on the size of the output, not
|
||||
the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer whole
|
||||
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.
|
||||
|
||||
## Releasing
|
||||
|
||||
```sh
|
||||
make patch # 0.27.1 -> next patch
|
||||
make minor # 0.27.1 -> next minor
|
||||
make major # 0.27.1 -> next major
|
||||
```
|
||||
|
||||
Each bumps `Cargo.toml` and `Cargo.lock`, folds that bump into the last commit, and tags it
|
||||
`v<version>`. One action, so no bump is left untagged and no tag lands without a bump. In this repo
|
||||
it also appends `, and bump to <version>` to the commit's subject, the way the release commits
|
||||
before it read.
|
||||
|
||||
It refuses to run when the working tree is dirty, when `HEAD` is already tagged, or when `HEAD` is
|
||||
already pushed. The first asks you to decide whether that work belongs in the version; the other two
|
||||
mean the amend would orphan a tag or need a force push.
|
||||
|
||||
+323
@@ -0,0 +1,323 @@
|
||||
---
|
||||
name: worklane-admin
|
||||
description: Set up and repair a worklane board itself, whatever it tracks: design and annotate the tag vocabulary with `worklane tags`, retire or rename a tag, and fix a board whose files and fields disagree, such as a ticket missing from `ls`, a duplicated id, a stray temp file or a move that will not go through. Use when the subject is the board's own configuration or health. Not for filing, working or reviewing a ticket, and not for priorities, due dates or campaigns.
|
||||
---
|
||||
|
||||
# Administering a worklane board
|
||||
|
||||
For "set up a board for this", "what tags should this board have", "add a tag", "what
|
||||
does this tag mean", "the board is in a weird state", "this ticket has gone missing".
|
||||
The subject is the board itself: the vocabulary it files against, and the parts that can
|
||||
come apart.
|
||||
|
||||
The CLI is the `worklane` skill: the statuses, how a ticket is addressed, which command
|
||||
owns which field. Read it too.
|
||||
|
||||
**This is not `worklane-plan`.** That skill grooms the work: priorities, due dates,
|
||||
retagging tickets, campaigns. This one decides what the tags *are* and puts the board
|
||||
back together. The line between them is the tag section: designing and annotating the
|
||||
vocabulary is here, applying it across tickets is there.
|
||||
|
||||
## A board is not only for software
|
||||
|
||||
Everything below holds for a board tracking a product strategy, a house move or a term's
|
||||
teaching, and the worked examples say so. What changes between domains is the tags, never
|
||||
the shape. Nothing in worklane knows what your tickets are about.
|
||||
|
||||
Two things you do not get to configure, whatever the board is for:
|
||||
|
||||
- **The four statuses.** `backlog`, `committed`, `reviewing`, `done`, in that order, one
|
||||
step at a time. There is no way to rename them or add a fifth. If a board wants a
|
||||
waiting-on-someone-else state, that is a tag, and the ticket stays in `committed`.
|
||||
- **The fields.** Priority 1 to 5, Due, Owner, Tags, Campaign. A board that wants a
|
||||
concept these do not cover expresses it as a tag or a campaign, not as a new field.
|
||||
|
||||
So the tag vocabulary is where a board is fitted to its subject, and it is most of this
|
||||
document.
|
||||
|
||||
## Starting a board
|
||||
|
||||
```
|
||||
worklane init # in the directory the board belongs to
|
||||
```
|
||||
|
||||
Which directory decides which board. Commands walk up from the working directory to the
|
||||
nearest `.worklane`, so a board in `~/house` answers every `worklane` run from anywhere
|
||||
under `~/house` and nowhere else.
|
||||
|
||||
`init` makes the four status directories, the campaigns directory and an empty `tags.md`.
|
||||
Run on a board that already exists it prints a line and changes nothing, which is what
|
||||
makes it safe to run when you are not sure.
|
||||
|
||||
Then declare the vocabulary before the tickets pile up. Tags applied for months are far
|
||||
harder to change than tags agreed once, because changing one means rewriting every ticket
|
||||
carrying it.
|
||||
|
||||
## Designing a tag vocabulary
|
||||
|
||||
A tag is a word a ticket carries so the board can be cut by it later. `worklane ls --tag
|
||||
kitchen` is the whole payoff, so the test of a good vocabulary is whether the cuts it
|
||||
allows are cuts anyone wants.
|
||||
|
||||
### Work in axes
|
||||
|
||||
An axis is one question every ticket on this board can answer, with a small closed set of
|
||||
answers. Pick two or three axes and keep them apart. Nearly every vocabulary that goes
|
||||
bad is one where two axes were mixed into one pile of words.
|
||||
|
||||
A software tool:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `feature`, `bug`, `chore`, `docs` |
|
||||
| Area | `cli`, `tui`, `api`, `build` |
|
||||
|
||||
A product strategy:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `research`, `decision`, `experiment`, `writeup` |
|
||||
| Audience | `enterprise`, `self-serve`, `internal` |
|
||||
|
||||
A household:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `repair`, `errand`, `admin`, `cleaning` |
|
||||
| Room | `kitchen`, `garden`, `garage`, `car` |
|
||||
|
||||
Same shape, nothing in common. Derive the axes from the questions somebody will actually
|
||||
ask this board, not from a template: if nobody will ever ask "show me everything in the
|
||||
garage", `garage` is not earning its place.
|
||||
|
||||
### The rules
|
||||
|
||||
- **A tag is for kind, not for state.** State is the status directory. A `doing` tag
|
||||
beside `committed`, a `blocked` tag beside a `blocked by` relation, a `done` tag at all:
|
||||
each is a second copy of something the board already knows, and the copy is the one that
|
||||
goes stale.
|
||||
- **A tag is not a goal.** Everything for one outcome is a campaign, which has a title, a
|
||||
description and a state derived from its members. `worklane campaign` owns that;
|
||||
`worklane-plan` decides what belongs in one.
|
||||
- **A tag is not a field.** No `p1` beside Priority, no `alice` beside Owner, no `august`
|
||||
beside Due. The field is the writer and the tag will disagree with it.
|
||||
- **A tag is not a person.** Owner is a field, and `chown` writes it.
|
||||
- **Two axes, not two words for one thing.** Before adding a word, say which axis it is
|
||||
on. If it does not fit one, either it is a new axis, which is a decision, or it is a
|
||||
private note, which is not a tag.
|
||||
- **Around a dozen tags, up to twenty.** Past that nobody remembers the vocabulary, so
|
||||
they invent a near-duplicate instead of reusing what is there. Fewer, broader tags beat
|
||||
a long tail nobody can recall.
|
||||
- **Singular or plural, pick one and keep to it.** `bug`/`bugs` and `chore`/`chores` are
|
||||
the commonest way a board ends up with two words for one idea.
|
||||
- **Case matters.** `Bug` and `bug` are two tags to `--tag`, to `tags` and to the colour
|
||||
a card is drawn in. Lowercase everything unless there is a reason.
|
||||
|
||||
### How many tags per ticket
|
||||
|
||||
One per axis is the target: a ticket is one kind of thing in one area. A ticket that wants
|
||||
three areas is usually two tickets, and a ticket with no tag at all is invisible to every
|
||||
question asked by tag.
|
||||
|
||||
## Annotating a tag
|
||||
|
||||
```
|
||||
worklane tags # every tag, its count and what it means
|
||||
worklane tags add kitchen --annotation "..." # declare one, and say what it means
|
||||
worklane tags set kitchen --annotation "..." # change what it means
|
||||
```
|
||||
|
||||
`.worklane/tags.md` holds one section per declared tag, the tag as the heading and its
|
||||
annotation under it. It is what a person opens to find out what the board means by a word,
|
||||
and it is what an agent reads before choosing one.
|
||||
|
||||
**Declaring a tag tags nothing, and tagging a ticket declares nothing.** The two lists are
|
||||
separate on purpose: the counts come from what the tickets carry, `tags.md` records what
|
||||
the board agreed on, and the difference between them is the thing worth looking at. A tag
|
||||
carried by tickets but never declared is a word somebody invented in a hurry.
|
||||
|
||||
`worklane tags` reports both, as the tag, a tab, the count, and a tab and the annotation's
|
||||
opening line for a tag that is declared. So the two cases worth finding read off the
|
||||
listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with
|
||||
no annotation column at all is carried and was never declared.
|
||||
|
||||
### What an annotation has to say
|
||||
|
||||
The definition is the easy half and does the least work. What stops drift is the boundary
|
||||
against the neighbouring tag, so write that.
|
||||
|
||||
Worthless, because nobody was ever unsure of this:
|
||||
|
||||
```
|
||||
worklane tags add bug --annotation "Bugs."
|
||||
```
|
||||
|
||||
Useful, because it answers the question somebody was actually about to get wrong:
|
||||
|
||||
```
|
||||
worklane tags add bug \
|
||||
--annotation "Behaviour that contradicts what the tool says it does, reproducible from a described state." \
|
||||
--annotation "" \
|
||||
--annotation "Not for something missing. A gap is a feature, however obvious the gap is."
|
||||
```
|
||||
|
||||
The same for a household board:
|
||||
|
||||
```
|
||||
worklane tags add repair \
|
||||
--annotation "Something that worked and now does not." \
|
||||
--annotation "" \
|
||||
--annotation "Not for an improvement to something that works, which is a project, and not for a thing that needs replacing rather than fixing."
|
||||
```
|
||||
|
||||
Repeat `--annotation` for more lines, and pass an empty one for a paragraph break. Three
|
||||
lines is plenty: a definition, then the boundary.
|
||||
|
||||
Write an annotation for every tag, including the obvious ones. The obvious tags are the
|
||||
ones two people quietly disagree about.
|
||||
|
||||
### Traps
|
||||
|
||||
- `tags add` refuses a tag that is already declared, and `tags set` refuses one that is
|
||||
not. Each names the other, so the refusal tells you which you wanted.
|
||||
- A tag cannot contain a comma, because a comma is what separates one tag from the next in
|
||||
the Tags field. Surrounding spaces are trimmed.
|
||||
- A tag you have declared and never applied lists at a count of zero. That is not a fault;
|
||||
it is the file and the board disagreeing, which is the state that tells you the
|
||||
vocabulary has not landed yet.
|
||||
- Nothing removes a declaration. There is no `tags rm`, so a tag declared in error stays
|
||||
in the file with whatever its annotation says. Say it is retired in the annotation.
|
||||
|
||||
## Changing the vocabulary later
|
||||
|
||||
### Renaming a tag
|
||||
|
||||
There is no rename. The tag is the key, so it means rewriting the Tags field of every
|
||||
ticket carrying it, one at a time:
|
||||
|
||||
```
|
||||
worklane ls --tag bugs --ids # every ticket carrying the old word
|
||||
worklane show 1b78a24 # read the whole Tags field of each
|
||||
worklane set 1b78a24 --tags bug,cli # restate all of them, with the new word
|
||||
worklane tags add bug --annotation "..."
|
||||
```
|
||||
|
||||
**`--tags` replaces the whole field.** Restate every tag the ticket should keep or the
|
||||
ones you leave out are gone, with no undo. This is the most destructive command on the
|
||||
board. Read the ticket's current tags before writing, never from memory, and run
|
||||
`worklane tags` before and after: a count that moved where nothing was meant to change is
|
||||
a tag lost to that rule.
|
||||
|
||||
Propose the whole list of edits and wait for approval before applying any of them, the way
|
||||
`worklane-plan` requires for a sweep. The reason is the same: nothing records what a field
|
||||
held before you wrote to it.
|
||||
|
||||
### Retiring a tag
|
||||
|
||||
Take it off the tickets the same way, then leave the declaration saying it is retired and
|
||||
what replaced it. A tag with a count of zero and an annotation pointing elsewhere is a
|
||||
better answer than a word that simply vanishes, because the next person will otherwise
|
||||
reinvent it.
|
||||
|
||||
## Repairing a board
|
||||
|
||||
Every repair here has been run against a real board. Work by symptom.
|
||||
|
||||
**The rule that does not bend: do not edit a ticket file.** The filename, the `Status`
|
||||
field and the directory have to agree, and the commands are what keep them agreeing. The
|
||||
two exceptions below are files no command owns, and they are marked as such.
|
||||
|
||||
### A ticket has vanished from `ls`
|
||||
|
||||
`worklane ls` leaves `done` out of its listing, though it still counts it at the top. So
|
||||
first check `worklane ls done`. If it is there and should not be, its file has been moved
|
||||
into the wrong directory by hand or by a restore.
|
||||
|
||||
The repair is two moves, not one:
|
||||
|
||||
```
|
||||
worklane mv 1b78a24 --status reviewing -f
|
||||
worklane mv 1b78a24 --status done -f
|
||||
```
|
||||
|
||||
`mv` reads the current status from the *directory*, so moving it to the status the
|
||||
directory already says it is in is refused as a no-op and the field stays wrong. Moving it
|
||||
away and back rewrites the field. Check with `worklane show 1b78a24`, whose `Status` line
|
||||
is read from the file rather than from where it sits.
|
||||
|
||||
### A command says the id matches several tickets
|
||||
|
||||
```
|
||||
Multiple tickets found matching 'bf2dc18':
|
||||
1. (bf2dc18) Alpha [backlog]
|
||||
2. (bf2dc18) Alpha [done]
|
||||
```
|
||||
|
||||
The same file exists in two status directories, usually from a copy or a half-finished
|
||||
restore. The ticket is now unaddressable: every command resolves before it acts, so `show`
|
||||
and `mv` fail the same way and cannot be used to fix it.
|
||||
|
||||
**File exception.** Read both with `cat`, keep the one whose `Status` field agrees with
|
||||
the directory it is in, and delete the other. If neither agrees, keep either and repair it
|
||||
as above. Then confirm with `worklane show`.
|
||||
|
||||
### A move is refused by a blocker
|
||||
|
||||
```
|
||||
Cannot move 'Beta' while it is blocked by:
|
||||
...
|
||||
Use --force (-f) to move it anyway.
|
||||
```
|
||||
|
||||
Working as intended: a ticket cannot advance while something it waits on is unfinished.
|
||||
Finish the blocker, or use `-f` if the dependency is no longer real. Note that the
|
||||
relation stays on the ticket and will refuse the next move too, and there is no way to
|
||||
take a relation off, so `-f` is the answer every time until the blocker is done.
|
||||
|
||||
If the message says `is blocked by X, which is not on the board`, the blocker has been
|
||||
deleted. That is a warning rather than a refusal and the move goes through.
|
||||
|
||||
### `show` renders `_missing_`
|
||||
|
||||
A relation or a Campaign field naming something the board no longer holds. Harmless to
|
||||
read and impossible to clear, since `relate` only adds and `assign` only moves a ticket
|
||||
between campaigns that exist. For a campaign, `worklane assign <a-real-campaign> <ticket>`
|
||||
overwrites it. For a relation, leave it.
|
||||
|
||||
### A status is missing from `worklane ls`
|
||||
|
||||
The count list at the top of `ls` names every status directory it found, so a status that
|
||||
is absent from it has had its directory deleted. Nothing errors until something tries to
|
||||
move a ticket there, which then fails with a raw file error.
|
||||
|
||||
**File exception.** `worklane init` will not repair it, since it refuses on a board that
|
||||
already exists. Recreate the directory:
|
||||
|
||||
```
|
||||
mkdir .worklane/reviewing
|
||||
```
|
||||
|
||||
### A `.wl-*.tmp` file in `.worklane/`
|
||||
|
||||
The staging file for a write that was killed part way. Every write stages here and renames
|
||||
into place, so a leftover means the write did not finish; nothing reads these and no
|
||||
listing shows them.
|
||||
|
||||
**File exception.** Delete it. Then check the ticket it names with `worklane show` and
|
||||
redo whatever the interrupted command was.
|
||||
|
||||
### Nothing works and the error names `.worklane`
|
||||
|
||||
Check where you are. Commands resolve the nearest `.worklane` at or above the working
|
||||
directory, so running from the wrong directory addresses another board or none. `worklane
|
||||
ls` from where you think the board is, is the fastest way to find out.
|
||||
|
||||
## What this skill does not touch
|
||||
|
||||
- **Priorities, due dates, campaign membership and retagging sweeps.** That is
|
||||
`worklane-plan`. Deciding the vocabulary is here; applying it across the board is there.
|
||||
- **Filing a ticket, working one, moving it through the statuses.** That is the `worklane`
|
||||
skill.
|
||||
- **Judging whether a finished ticket is really done.** That is `worklane-review`.
|
||||
- **The content of a ticket.** A description or an acceptance criterion that is wrong is
|
||||
the author's, and the answer is a comment on that ticket.
|
||||
+19
-1
@@ -136,6 +136,14 @@ field on purpose, which is a different thing from emptying it by forgetting a ta
|
||||
proposed: a count that dropped where nothing was meant to change is a tag lost to the
|
||||
replace-the-whole-field rule above.
|
||||
|
||||
**Designing the vocabulary is the `worklane-admin` skill, not this one.** What the tags
|
||||
should be, what each one means, how one is declared with `worklane tags add` and annotated
|
||||
so the next person picks the same word: read that document before proposing a vocabulary,
|
||||
and read `.worklane/tags.md` before proposing a tag. This section is the sweep over
|
||||
tickets already tagged, which is a different job. A board whose tags are declared has an
|
||||
annotation per tag, and a ticket that contradicts one is mis-tagged against a written
|
||||
standard rather than against your reading of the board.
|
||||
|
||||
Derive the vocabulary from the board rather than inventing one. Read `worklane tags`, count
|
||||
what is actually used, and show the count before proposing anything. What to report:
|
||||
|
||||
@@ -160,7 +168,8 @@ fields; a goal is a campaign.
|
||||
worklane campaign ls
|
||||
worklane campaign show v1
|
||||
worklane campaign add --title "..." --codename v1 --description "..."
|
||||
worklane campaign set v1 --title "..." # or --codename, on one already filed
|
||||
worklane campaign set v1 --title "..." # or --description or --codename, on one already filed
|
||||
worklane campaign append v1 -d "..." # add a paragraph to the description
|
||||
worklane assign v1 1b78a24
|
||||
```
|
||||
|
||||
@@ -186,6 +195,12 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
|
||||
- **Do not propose renaming a codename a campaign already has.** It is what the campaign is
|
||||
called on every card in it and at the command line, so changing it is churn dressed as
|
||||
grooming. `campaign set` refuses it without `--force` for that reason.
|
||||
- **A campaign's description is editable, so a wrong one is a fix rather than a refiling.**
|
||||
A container whose description no longer describes what its members are for is worth
|
||||
pointing out: it is the line every one of those tickets was filed against. `campaign set
|
||||
--description` replaces it and `campaign append --description` adds to it, so neither
|
||||
needs the campaign refiled and its members reassigned. Adding to it is the usual answer;
|
||||
replacing prose to add a sentence to it is how the rest of it gets lost.
|
||||
|
||||
Proposing a campaign means naming the goal, the members, and what is deliberately left
|
||||
out of it. The last part is what makes it a goal rather than a pile.
|
||||
@@ -199,6 +214,9 @@ out of it. The last part is what makes it a goal rather than a pile.
|
||||
columns is reporting progress that did not happen.
|
||||
- **Owner.** `chown` records a commitment a person made. Propose it, do not write it,
|
||||
unless you were asked to assign the work.
|
||||
- **The tag vocabulary itself, and the state of the board's own files.** Declaring a tag,
|
||||
writing what it means, retiring one, or repairing a ticket whose file and fields have
|
||||
come apart: all `worklane-admin`. A sweep applies the vocabulary, it does not decide it.
|
||||
- **New tickets.** Grooming is about what is on the board. Something genuinely missing is
|
||||
worth filing, by the rules in the `worklane` skill, but say it is a new ticket rather
|
||||
than folding it into a grooming sweep.
|
||||
|
||||
+12
-4
@@ -211,7 +211,8 @@ worklane campaign add --title "First public release" --codename v1 \
|
||||
worklane campaign ls # every campaign, its codename, how far it has got
|
||||
worklane campaign ls --ids # id and title, tab separated, like ls --ids
|
||||
worklane campaign show v1 # its body, then its members by status
|
||||
worklane campaign set v1 --title "..." # replace the title or the codename
|
||||
worklane campaign set v1 --title "..." # replace the title, description or codename
|
||||
worklane campaign append v1 -d "..." # add a paragraph to the description
|
||||
worklane assign v1 1b78a24 # put a ticket in it
|
||||
worklane ls --campaign v1 # only that campaign's tickets
|
||||
```
|
||||
@@ -226,9 +227,16 @@ existed needs. **Replacing a codename it already has needs `--force`**: that wor
|
||||
the campaign is referred to on the board and at the command line, so changing it is a
|
||||
decision rather than a correction. Setting the one it already has is a no-op either way.
|
||||
|
||||
`campaign set` is the only way to change a campaign after it is filed, and it reaches the
|
||||
title and the codename only. There is no way to edit a campaign's description or its owner
|
||||
yet.
|
||||
`campaign set` and `campaign append` are the only ways to change a campaign after it is
|
||||
filed. `set` replaces the title, the description or the codename; `append` adds a paragraph
|
||||
to the description, which is what to use when the description is right and only incomplete,
|
||||
since replacing prose to add a sentence to it is how the rest of it gets lost. An empty
|
||||
`--description ""` between two values is a paragraph break, exactly as it is for a ticket,
|
||||
and a call whose every value is blank is refused: a campaign's description cannot be
|
||||
emptied. There is still no way to change a campaign's owner.
|
||||
|
||||
`append` here is `campaign append` and not the top-level `append`, which takes a ticket. The
|
||||
two objects are addressed the same way, so the command is what says which one is meant.
|
||||
|
||||
`assign` takes the **campaign first and the ticket second**, like `chown`, and is the
|
||||
only writer of the field. `add` has no `--campaign` and neither has `set`, so membership
|
||||
|
||||
+63
-16
@@ -358,10 +358,18 @@ pub enum Command {
|
||||
/// No `mv`: a campaign has no status to move it to, its state is derived from its
|
||||
/// members.
|
||||
///
|
||||
/// No `append`, and therefore no `set --description`: `set` and `append` are a pair for a
|
||||
/// prose section, and a way to replace a description with no way to add a paragraph to one
|
||||
/// is half of it. That pair is its own ticket. `set` here carries the two scalars, which
|
||||
/// have no append form at all, the same line `append` already draws for a ticket.
|
||||
/// `set` and `append` arrive together, 32e98ab, because for a prose section they are a
|
||||
/// pair: a way to replace a description with no way to add a paragraph to one is the half
|
||||
/// that is easy to reach for and wrong, since replacing a description to add a sentence is
|
||||
/// how the rest of it gets lost. The two scalars have no append form at all, which is the
|
||||
/// same line `append` already draws for a ticket.
|
||||
///
|
||||
/// **`append` is a campaign's own subcommand and not the top-level `append`.** That one
|
||||
/// resolves a ticket, and its positional would then name either object: `resolve_in`'s tiers
|
||||
/// are the same over both directories, so a search can resolve in each and nothing but a
|
||||
/// flag could say which was meant. It would also make a liar of `resolve_ticket`, which
|
||||
/// explains a ticket search that names a campaign. Under `campaign` the object is settled by
|
||||
/// the command, the way it is for `set`, `show` and `ls`.
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum CampaignCommand {
|
||||
/// File a new campaign
|
||||
@@ -369,11 +377,19 @@ pub enum CampaignCommand {
|
||||
|
||||
/// Replace fields on an existing campaign
|
||||
///
|
||||
/// The only way to change a campaign after it is filed. `campaign add --codename` writes
|
||||
/// the field at creation the way `add --title` does for a ticket; this is what replaces
|
||||
/// it, so every campaign filed before the field existed can still be given one.
|
||||
/// The only way to change a campaign's title or codename after it is filed.
|
||||
/// `campaign add --codename` writes the field at creation the way `add --title` does for
|
||||
/// a ticket; this is what replaces it, so every campaign filed before the field existed
|
||||
/// can still be given one.
|
||||
Set(CampaignSetArgs),
|
||||
|
||||
/// Add a paragraph to a campaign's description
|
||||
///
|
||||
/// The other half of `campaign set --description`, and the half that keeps what is
|
||||
/// already written: a description is the sentence a whole campaign's members are filed
|
||||
/// against, so adding a line to it must not mean retyping it.
|
||||
Append(CampaignAppendArgs),
|
||||
|
||||
/// List campaigns with their member counts
|
||||
Ls {
|
||||
/// Print one campaign per line as its id and title, tab separated, for a script
|
||||
@@ -394,25 +410,30 @@ pub enum CampaignCommand {
|
||||
},
|
||||
}
|
||||
|
||||
/// What can be replaced on a campaign that is already filed: its title and its codename.
|
||||
///
|
||||
/// The two scalars, and deliberately not the description. See [`CampaignCommand`].
|
||||
/// What can be replaced on a campaign that is already filed: everything it holds but its
|
||||
/// owner.
|
||||
///
|
||||
/// No `--owner`: nothing writes a campaign's Owner today, and giving `set` one would settle
|
||||
/// by accident whether `chown` grows a campaign or `set` keeps the field, which is the
|
||||
/// one-field-one-writer question and not this command's to answer.
|
||||
///
|
||||
/// No `--clear`: nothing has asked to empty a codename, a wrong one is replaced rather than
|
||||
/// emptied, and the vocabulary is a real question — `Clearable` is `SetArgs`'s and its
|
||||
/// variants are a ticket's fields, so reusing it here would put a ticket's enum on a
|
||||
/// campaign and inventing a second one is a decision worth making on purpose.
|
||||
/// No `--clear`, which is 32e98ab's decision and not a deferral. A codename is replaced
|
||||
/// rather than emptied, and a campaign's one prose section has no cleared form worth
|
||||
/// reaching: emptying the description of a container six tickets are filed against is not a
|
||||
/// thing anybody has asked for, and the only ways to spell it would be to put [`Clearable`]
|
||||
/// on a campaign, whose variants are a ticket's fields, or to invent a second enum with one
|
||||
/// variant in it. So an empty `--description ""` stays a paragraph break here exactly as it
|
||||
/// is everywhere else, and the refusal for an all-blank value says there is nowhere to go
|
||||
/// back to rather than naming a flag that does not exist.
|
||||
///
|
||||
/// `--force` guards the codename and nothing else. A campaign that already has one is
|
||||
/// referred to by it: it is on every card in the campaign, it is what resolves it at the
|
||||
/// command line, and it is very likely in somebody's shell history. Replacing that silently
|
||||
/// is the same mistake overwriting an edited skill document would be, which is what
|
||||
/// `install-skill --force` exists for. A title needs no guard, since a campaign always has
|
||||
/// one and replacing it is the whole point of the flag.
|
||||
/// one and replacing it is the whole point of the flag. Neither does a description: it is
|
||||
/// prose written to be revised, the same reason `tags set --annotation` has no guard, and a
|
||||
/// guard in front of the command's whole purpose is worse than no command.
|
||||
///
|
||||
/// The group makes at least one field mandatory, so a bare `worklane campaign set <c>` is a
|
||||
/// usage error rather than a silent no-op, exactly as it is for [`SetArgs`].
|
||||
@@ -421,7 +442,7 @@ pub enum CampaignCommand {
|
||||
clap::ArgGroup::new("campaign_set_fields")
|
||||
.required(true)
|
||||
.multiple(true)
|
||||
.args(["title", "codename"])
|
||||
.args(["title", "description", "codename"])
|
||||
))]
|
||||
pub struct CampaignSetArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
@@ -431,6 +452,13 @@ pub struct CampaignSetArgs {
|
||||
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
|
||||
pub title: Option<String>,
|
||||
|
||||
/// Replace the description. Repeat the flag for more lines, empty for a paragraph break
|
||||
///
|
||||
/// The whole section, so a paragraph added to it is `campaign append --description`
|
||||
/// rather than the description retyped
|
||||
#[arg(short, long, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
|
||||
/// Replace the codename, a single word to call the campaign by
|
||||
///
|
||||
/// The same parser `campaign add --codename` takes, so a codename is one thing however
|
||||
@@ -449,6 +477,25 @@ pub struct CampaignSetArgs {
|
||||
pub force: bool,
|
||||
}
|
||||
|
||||
/// What can be added to a campaign that is already filed: a paragraph of its description.
|
||||
///
|
||||
/// One field, so it is `required` rather than a group of one, which is the longer way to say
|
||||
/// the same thing and the shape [`TagSetArgs`] already takes. A bare
|
||||
/// `worklane campaign append <c>` is therefore a usage error rather than a silent no-op.
|
||||
///
|
||||
/// No `--title` and no `--codename`, because appending to a scalar has no meaning. That is
|
||||
/// the line `append` already draws for a ticket, where the title is absent for the same
|
||||
/// reason.
|
||||
#[derive(clap::Args)]
|
||||
pub struct CampaignAppendArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
pub campaign: String,
|
||||
|
||||
/// Add a paragraph to the description. Repeat the flag for more lines within it
|
||||
#[arg(short, long, required = true, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
}
|
||||
|
||||
/// What a campaign holds: a title, a description and an owner.
|
||||
///
|
||||
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
|
||||
|
||||
+51
-10
@@ -50,11 +50,16 @@ pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"];
|
||||
|
||||
/// Nested subcommands whose first argument is a campaign, as `parent child`.
|
||||
///
|
||||
/// `campaign show` and `campaign set`, and they are why the fish half needs a third
|
||||
/// position helper: their argument is the *third* token, where `__worklane_first_arg_of`
|
||||
/// reads the second and `__worklane_second_arg_of` counts a top-level command's arguments.
|
||||
/// Neither can tell `campaign show <TAB>` from `chown alice <TAB>` by position.
|
||||
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 2] = [("campaign", "show"), ("campaign", "set")];
|
||||
/// `campaign show`, `campaign set` and `campaign append`, and they are why the fish half
|
||||
/// needs a third position helper: their argument is the *third* token, where
|
||||
/// `__worklane_first_arg_of` reads the second and `__worklane_second_arg_of` counts a
|
||||
/// top-level command's arguments. Neither can tell `campaign show <TAB>` from
|
||||
/// `chown alice <TAB>` by position.
|
||||
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [
|
||||
("campaign", "show"),
|
||||
("campaign", "set"),
|
||||
("campaign", "append"),
|
||||
];
|
||||
|
||||
/// Options whose value is a campaign.
|
||||
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
@@ -192,14 +197,21 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
|
||||
-x -a '(worklane campaign ls --ids)'
|
||||
|
||||
# Tags come from `worklane tags` rather than from a listing of objects, since a tag has no
|
||||
# id. The count after the tab lands as fish's description, which is what makes the list
|
||||
# worth reading: it says which spelling the board actually uses.
|
||||
complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)'
|
||||
# id. Three fields now, the tag, its count and its annotation, and fish takes everything
|
||||
# after the *first* tab as one description, so the count is dropped here rather than landing
|
||||
# in the middle of the prose. `cut` and not `string replace` because the columns are what is
|
||||
# being picked, and `cut -f1` is how a script reads this listing anyway.
|
||||
#
|
||||
# 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)'
|
||||
|
||||
# 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
|
||||
# here are the values it refuses.
|
||||
complete -c worklane -n '{tag_nested}' -a '(worklane tags)'
|
||||
complete -c worklane -n '{tag_nested}' -a '(worklane tags | cut -f1,3)'
|
||||
|
||||
# `chown --clear` names the ticket in the flag too, since with no user to give there is
|
||||
# no second positional to put it in. Scoped to `chown`, unlike the rule above: `set`
|
||||
@@ -367,7 +379,10 @@ mod tests {
|
||||
|
||||
// A guard on the walker itself: if it stopped finding arguments, every assertion
|
||||
// above would pass by never running.
|
||||
assert_eq!(seen, 4, "expected assign, campaign show, campaign set and ls --campaign");
|
||||
assert_eq!(
|
||||
seen, 5,
|
||||
"expected assign, campaign show, campaign set, campaign append and ls --campaign"
|
||||
);
|
||||
}
|
||||
|
||||
/// Commands whose tag positional names a tag that does not exist yet.
|
||||
@@ -514,6 +529,32 @@ mod tests {
|
||||
assert!(script.contains("__worklane_first_arg_of assign"), "{script}");
|
||||
}
|
||||
|
||||
/// Every rule that reads the tag listing drops the count, because `worklane tags` prints
|
||||
/// three fields and fish takes everything after the first tab as the description. Left
|
||||
/// whole, a tag would be described as its count, a tab and its annotation.
|
||||
///
|
||||
/// Pinned per rule rather than once over the script: a rule added later that reads
|
||||
/// `worklane tags` raw is the bug this catches, and it would not show up in a single
|
||||
/// `contains`.
|
||||
#[test]
|
||||
fn every_tag_rule_takes_the_annotation_as_its_description() {
|
||||
let script = fish_dynamic();
|
||||
|
||||
let reading: Vec<&str> = script
|
||||
.lines()
|
||||
.filter(|line| line.contains("(worklane tags"))
|
||||
.collect();
|
||||
|
||||
assert_eq!(
|
||||
reading.len(),
|
||||
2,
|
||||
"expected the ls --tag rule and the tags set one: {reading:?}"
|
||||
);
|
||||
for line in reading {
|
||||
assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}");
|
||||
}
|
||||
}
|
||||
|
||||
/// The one status positional and the one shell positional, which clap does not emit
|
||||
/// possible values for. Read off the enums, so a fifth status would appear here on
|
||||
/// its own.
|
||||
|
||||
+127
-30
@@ -7,8 +7,8 @@ use std::path::Path;
|
||||
|
||||
use crate::campaign::*;
|
||||
use crate::command::{
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs,
|
||||
RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs,
|
||||
ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
|
||||
};
|
||||
use crate::install;
|
||||
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
|
||||
@@ -784,6 +784,42 @@ fn section_args<'a>(
|
||||
]
|
||||
}
|
||||
|
||||
/// The lines a caller's values amount to, or the refusal an all-blank call earns.
|
||||
///
|
||||
/// An empty value is a paragraph break, so a call whose values are *every one* blank asked
|
||||
/// for nothing, and writing an empty section is not what it meant. Shared by `set` and
|
||||
/// `campaign set` because the rule is the section's rather than the object's.
|
||||
///
|
||||
/// `instead` is the way out, and it is the caller's because the callers differ: a ticket's
|
||||
/// section is emptied with `--clear <field>`, and a campaign's description has no cleared
|
||||
/// form at all, per [`CampaignSetArgs`].
|
||||
fn replaced_items(section: &Section, values: &[String], instead: &str) -> Result<Vec<String>> {
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"An empty value is a paragraph break, not a way to empty the {}: {}",
|
||||
section.label,
|
||||
instead
|
||||
));
|
||||
}
|
||||
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// The same for `append`, which has no way out to name: appending nothing was never a way
|
||||
/// to empty anything, so the message says only that there was nothing to add.
|
||||
fn appended_items(section: &Section, values: &[String]) -> Result<Vec<String>> {
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"Nothing to append to the {}: every value given was blank",
|
||||
section.label
|
||||
));
|
||||
}
|
||||
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// Write the ticket back, renaming the file when a new title changes its slug.
|
||||
///
|
||||
/// The content goes down first and the rename second, the same order and for the same
|
||||
@@ -917,14 +953,8 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
|
||||
continue;
|
||||
}
|
||||
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"An empty value is a paragraph break, not a way to empty the {}: use --clear {}",
|
||||
section.label,
|
||||
section.clear.map_or("", Clearable::name)
|
||||
));
|
||||
}
|
||||
let clear = format!("use --clear {}", section.clear.map_or("", Clearable::name));
|
||||
let items = replaced_items(section, values, &clear)?;
|
||||
|
||||
let next = set_section_body(&content, section, &items)?;
|
||||
apply(&mut content, &mut changed, section.label, next);
|
||||
@@ -1031,13 +1061,7 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
|
||||
continue;
|
||||
}
|
||||
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"Nothing to append to the {}: every value given was blank",
|
||||
section.label
|
||||
));
|
||||
}
|
||||
let items = appended_items(section, values)?;
|
||||
|
||||
content = append_section_body(&content, section, &items)?;
|
||||
changed.push(section.label);
|
||||
@@ -1217,27 +1241,52 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Every tag on the board, with how many tickets carry it.
|
||||
/// Every tag on the board: the ones the tickets carry, the ones the file declares, and
|
||||
/// what each declared one means.
|
||||
///
|
||||
/// The vocabulary itself, which nothing else could answer: `ls --tag` filters by a tag
|
||||
/// already known, and the decorated listing does not print tags at all. A grooming sweep
|
||||
/// starts by asking what the vocabulary *is*, and `assets/PLAN.md` used to have to say
|
||||
/// that the question could only be answered by reading the tickets.
|
||||
///
|
||||
/// **The union of the two vocabularies, not either one.** Since `tags.md` exists there are
|
||||
/// two: the tags the file declares and the tags the tickets carry. A declared tag nothing
|
||||
/// carries lists at zero rather than being dropped, and a carried tag nothing declares
|
||||
/// still lists. Those two cases are the whole reason to declare tags at all, so this is
|
||||
/// the command that has to show them apart.
|
||||
///
|
||||
/// **Alphabetical, and case sensitive.** `--tag` matches a whole value case sensitively,
|
||||
/// so `bug` and `Bug` are two tags and listing them as one would hide the reason a filter
|
||||
/// came back short. Sorting puts them next to each other, which is where a near-duplicate
|
||||
/// is spotted.
|
||||
///
|
||||
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count.
|
||||
/// Fish reads what follows the tab as a description, a script takes `cut -f1`, and neither
|
||||
/// wants an escape sequence. Every status, done included, for the reason `ls --ids`
|
||||
/// includes it: a tag retired months ago is still part of the answer to what the
|
||||
/// vocabulary has been.
|
||||
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count, and
|
||||
/// a tab and the annotation's opening line for a tag the file declares. Fish reads what
|
||||
/// follows the first tab as a description, a script takes `cut -f1`, and neither wants an
|
||||
/// escape sequence.
|
||||
///
|
||||
/// **A carried but undeclared tag is marked by the absence of the third field**, which is
|
||||
/// where the shape comes from. Anything appended to the tag itself would have a completion
|
||||
/// offer a tag that does not exist, and anything added to the count would stop the second
|
||||
/// field being a number. Absence costs neither, and it buys the one property a marker
|
||||
/// could not: a board with no `tags.md` has every tag undeclared, so it prints two fields
|
||||
/// a line, which is byte for byte what this printed before the file existed. The shipped
|
||||
/// fish completion of an older version is still reading that.
|
||||
///
|
||||
/// Every status, done included, for the reason `ls --ids` includes it: a tag retired months
|
||||
/// ago is still part of the answer to what the vocabulary has been.
|
||||
pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
// Through the same `load` `tags add` uses, so a file that is there and cannot be read
|
||||
// is an error here too. The listing is the one tag command that could go on without the
|
||||
// file, and reporting a vocabulary while silently treating a broken file as no file is
|
||||
// the wrong half of the answer.
|
||||
let index = TagIndex::load(worklane_dir)?;
|
||||
|
||||
// BTreeMap rather than a sort afterwards: the order is the point, and the counting
|
||||
// wants a map anyway.
|
||||
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
|
||||
// wants a map anyway. Seeded from the vocabulary rather than merged into afterwards,
|
||||
// which is what puts a declared tag nothing carries in at zero.
|
||||
let mut counts: BTreeMap<String, usize> =
|
||||
index.names().map(|tag| (tag.to_string(), 0)).collect();
|
||||
|
||||
for status in status_dirs() {
|
||||
let status_path = worklane_dir.join(status);
|
||||
@@ -1253,7 +1302,10 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
}
|
||||
|
||||
for (tag, count) in counts {
|
||||
println!("{}\t{}", tag, count);
|
||||
match index.summary(&tag) {
|
||||
Some(summary) => println!("{tag}\t{count}\t{summary}"),
|
||||
None => println!("{tag}\t{count}"),
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
@@ -1381,6 +1433,18 @@ pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
|
||||
/// No-op detection compares the whole file, the way `set` and `chown` do, so setting a
|
||||
/// codename a campaign already carries writes nothing. That is a no-op and not a refusal:
|
||||
/// `--force` is about overwriting a *different* word, and there is nothing to overwrite.
|
||||
///
|
||||
/// **The description goes through `set_section_body` and the `DESCRIPTION` entry**, the
|
||||
/// section table `cmd_set` and `campaign_body` already read, so what a campaign's one prose
|
||||
/// section *is* stays decided in one place. A second definition scoped to campaigns would
|
||||
/// drift on the spelling of the heading, which is the drift `campaign_body` was written
|
||||
/// against.
|
||||
///
|
||||
/// A campaign whose Description heading is gone is refused by that call rather than given
|
||||
/// the section back through `ensure_section`. Every campaign the tool has ever filed carries
|
||||
/// the heading, so an insertion path here would be reachable only from a hand-edited file:
|
||||
/// that is the opposite of the Relations case, where `add` writes nothing and the insertion
|
||||
/// is the only path there is.
|
||||
pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
|
||||
@@ -1408,6 +1472,16 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
apply(&mut content, &mut changed, "title", next);
|
||||
}
|
||||
|
||||
if !args.description.is_empty() {
|
||||
let items = replaced_items(
|
||||
&DESCRIPTION,
|
||||
&args.description,
|
||||
"a campaign's description has no cleared form",
|
||||
)?;
|
||||
let next = set_section_body(&content, &DESCRIPTION, &items)?;
|
||||
apply(&mut content, &mut changed, DESCRIPTION.label, next);
|
||||
}
|
||||
|
||||
if let Some(codename) = &args.codename {
|
||||
let next = set_or_insert_metadata_field(&content, CODENAME_FIELD, codename, &title)?;
|
||||
apply(&mut content, &mut changed, "codename", next);
|
||||
@@ -1425,6 +1499,32 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Add a paragraph to a campaign's description.
|
||||
///
|
||||
/// The other half of `campaign set --description`, and `cmd_append` for a campaign: the same
|
||||
/// `append_section_body` and the same `DESCRIPTION` entry, so a paragraph lands under a
|
||||
/// campaign's description the way it lands under a ticket's, blank line and all. A campaign
|
||||
/// filed with no description holds the placeholder, and that is replaced rather than
|
||||
/// followed, which is `append_section_body`'s rule and not a case handled here.
|
||||
///
|
||||
/// No whole-file comparison, unlike `set`: every value blank is refused above, so there is
|
||||
/// nothing left that appends nothing. `cmd_append` says it the same way.
|
||||
///
|
||||
/// One section, so there is no loop and no list to report: what changed is the description
|
||||
/// or the call failed.
|
||||
pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
|
||||
|
||||
let items = appended_items(&DESCRIPTION, &args.description)?;
|
||||
let content = append_section_body(&campaign.content, &DESCRIPTION, &items)?;
|
||||
|
||||
save_campaign(&worklane_dir, &campaign.uuid, &campaign.title, None, &content)?;
|
||||
|
||||
report(&[DESCRIPTION.label], &campaign.title, "Appended to");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Show a campaign, then its members grouped by status.
|
||||
///
|
||||
/// Every status is shown, done included, unlike `ls`, which leaves done out of its
|
||||
@@ -1766,8 +1866,7 @@ mod tests {
|
||||
/// will not share a microsecond, but it is the whole point of the guard.
|
||||
#[test]
|
||||
fn a_colliding_stem_takes_the_next_name_and_keeps_the_first() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-test-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
let dir = Fixture::new("worklane-test");
|
||||
|
||||
let first = write_new_comment(&dir, "20260820_143012_123456", "first").unwrap();
|
||||
let second = write_new_comment(&dir, "20260820_143012_123456", "second").unwrap();
|
||||
@@ -1786,7 +1885,5 @@ mod tests {
|
||||
let mut names = vec![second.clone(), third.clone(), first.clone()];
|
||||
names.sort();
|
||||
assert_eq!(names, vec![first, second, third]);
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
+47
-1
@@ -69,11 +69,29 @@ pub const PLAN_SKILL: Asset = Asset {
|
||||
content: include_str!("../assets/PLAN.md"),
|
||||
};
|
||||
|
||||
/// The skill that sets a board up and puts one back together.
|
||||
///
|
||||
/// Its own document for the reason the two above are, and the split against `PLAN_SKILL`
|
||||
/// is the one worth stating: that document grooms the *work*, priorities and dates and
|
||||
/// campaigns, and this one configures the *board*, the tag vocabulary and the faults a
|
||||
/// board can develop. The tag section is where they meet, so each points at the other.
|
||||
///
|
||||
/// The one document that has to hold for a board that tracks no software at all. The other
|
||||
/// three describe a workflow that happens to be this repo's; a vocabulary skill written
|
||||
/// around `bug` and `cli` would teach nothing to a board tracking a household, so the
|
||||
/// examples in it deliberately span three subjects.
|
||||
pub const ADMIN_SKILL: Asset = Asset {
|
||||
name: "worklane-admin",
|
||||
what: "skill",
|
||||
relative: "worklane-admin/SKILL.md",
|
||||
content: include_str!("../assets/ADMIN.md"),
|
||||
};
|
||||
|
||||
/// Every skill this binary carries, in the order they install.
|
||||
///
|
||||
/// A `static` rather than a `const` so the slice borrowed from it outlives the
|
||||
/// statement that took it: a `const` is inlined at each use and the borrow dies there.
|
||||
pub static SKILLS: [Asset; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL];
|
||||
pub static SKILLS: [Asset; 4] = [SKILL, REVIEW_SKILL, PLAN_SKILL, ADMIN_SKILL];
|
||||
|
||||
/// The opencode tool definitions, the second kind of asset this binary carries.
|
||||
///
|
||||
@@ -466,6 +484,34 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
/// What makes the admin document usable on a board that tracks no software, and what
|
||||
/// keeps its repairs honest.
|
||||
///
|
||||
/// The domain examples are the first thing an edit would quietly drop, since every
|
||||
/// other skill here is written around this repo, and dropping them leaves a document
|
||||
/// that teaches a household board to file `cli` tickets. The two-step repair is the
|
||||
/// second: it looks like a typo until you have watched `mv` refuse the one-step
|
||||
/// version, which is why the ticket for this skill demanded every repair be run rather
|
||||
/// than reasoned about.
|
||||
#[test]
|
||||
fn the_admin_skill_stays_domain_neutral_and_keeps_its_verified_repairs() {
|
||||
for required in [
|
||||
"household", // the vocabulary section spans three subjects
|
||||
"product strategy", //
|
||||
"worklane tags add", // the vocabulary is declared through the CLI
|
||||
"--tags` replaces the whole field", // the destructive one, restated where it bites
|
||||
"two moves, not one", // the repair `mv` cannot do in one step
|
||||
"do not edit a ticket file",
|
||||
"File exception", // and the three places that rule does not reach
|
||||
"worklane-plan", // the boundary against the sweep document
|
||||
] {
|
||||
assert!(
|
||||
ADMIN_SKILL.content.contains(required),
|
||||
"the admin skill no longer says {required:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// The decisions that make the review document a review rather than a rewrite.
|
||||
///
|
||||
/// Each of these is a rule an edit would drop without breaking anything else: a
|
||||
|
||||
+17
-5
@@ -73,6 +73,7 @@ fn main() -> Result<()> {
|
||||
cmd_campaign_ls(&worklane_dir, ids)
|
||||
}
|
||||
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start),
|
||||
CampaignCommand::Append(args) => cmd_campaign_append(&args, &start),
|
||||
CampaignCommand::Show { campaign } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_show(&campaign, &worklane_dir)
|
||||
@@ -210,16 +211,23 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
|
||||
board.should_quit = true
|
||||
}
|
||||
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_detail(),
|
||||
// The frame's own height while it holds the selection, and the detail
|
||||
// overlay on a card. `Board::toggle_focused` rather than a condition here,
|
||||
// for the reason the scroll keys route there.
|
||||
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_focused(screen),
|
||||
KeyCode::Left | KeyCode::Char('h') => board.select_column(-1, screen),
|
||||
KeyCode::Right | KeyCode::Char('l') => board.select_column(1, screen),
|
||||
// Up and down stay on the selection, open detail view or not, so a
|
||||
// column can be read through without closing the modal. Scrolling the
|
||||
// open ticket is a page at a time.
|
||||
// open ticket is a page at a time, and so is scrolling the campaign
|
||||
// frame that up reaches from the top card of a column.
|
||||
KeyCode::Up | KeyCode::Char('k') => board.select_card(-1, screen),
|
||||
KeyCode::Down | KeyCode::Char('j') => board.select_card(1, screen),
|
||||
KeyCode::PageUp => board.scroll_detail(-1, screen),
|
||||
KeyCode::PageDown => board.scroll_detail(1, screen),
|
||||
// The open ticket first and the campaign frame behind it, which is
|
||||
// `Board::scroll_page` rather than a condition written here: the arms in
|
||||
// this dispatch are not reachable from a test.
|
||||
KeyCode::PageUp => board.scroll_page(-1, screen),
|
||||
KeyCode::PageDown => board.scroll_page(1, screen),
|
||||
// Tabs cycle rather than clamp, the way tabs everywhere do, and are
|
||||
// a no-op with a single board. Free of every other binding: the
|
||||
// columns took hjkl and the arrows.
|
||||
@@ -240,7 +248,11 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
// The way in to the campaign picker, like `/` is to the search prompt: from
|
||||
// the next keypress on `picker_key` above has the keyboard. Free of every
|
||||
// other binding, and `ctrl-c` is matched above this so quitting still wins.
|
||||
KeyCode::Char('c') => board.open_picker(),
|
||||
KeyCode::Char('c') => board.open_picker(tui::PickerKind::Campaign, screen),
|
||||
// The other axis the board is cut along, and the one `ls --tag` has
|
||||
// answered since 2f3796e. Free of every other binding: `tab` is its own
|
||||
// key code, not this letter.
|
||||
KeyCode::Char('t') => board.open_picker(tui::PickerKind::Tag, screen),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
+49
@@ -153,6 +153,55 @@ impl TagIndex {
|
||||
self.tags.contains_key(tag)
|
||||
}
|
||||
|
||||
/// Every tag the file declares, alphabetical, whatever the board carries.
|
||||
///
|
||||
/// The half of the listing the status directories cannot answer. A tag declared and
|
||||
/// never applied is carried by no ticket, so counting alone drops it, and that tag is
|
||||
/// most of the reason the file exists: a word the board agreed on and nobody has
|
||||
/// reached for yet is exactly what a grooming sweep wants to see.
|
||||
pub fn names(&self) -> impl Iterator<Item = &str> {
|
||||
self.tags.keys().map(String::as_str)
|
||||
}
|
||||
|
||||
/// What a tag means, whole, or `None` for a tag the file does not declare.
|
||||
///
|
||||
/// The raw section, paragraphs and all, where [`Self::summary`] is the one line a
|
||||
/// listing has room for. `Some("")` is a tag declared with nothing said about it, which
|
||||
/// the caller has to tell apart from `None`: the board draws the two in different
|
||||
/// sections.
|
||||
pub fn annotation(&self, tag: &str) -> Option<&str> {
|
||||
self.tags.get(tag).map(String::as_str)
|
||||
}
|
||||
|
||||
/// The opening line of what a tag means, or `None` for a tag the file does not declare.
|
||||
///
|
||||
/// The cut to one line lives here rather than on the parse, the way
|
||||
/// [`CampaignRow::summary`] takes one line off a description the read carries whole:
|
||||
/// the annotation is prose with paragraphs in it, and which view wants how much of it
|
||||
/// is the view's business.
|
||||
///
|
||||
/// **`None` is what marks a carried but undeclared tag**, since `cmd_tags` prints no
|
||||
/// third field for it. Nothing is appended to the tag itself and nothing is added to
|
||||
/// the count, so `cut -f1` still yields the tag values and a board with no file at all
|
||||
/// lists what it listed before the file existed.
|
||||
///
|
||||
/// A declared tag with nothing said about it answers [`NO_ANNOTATION`] rather than an
|
||||
/// empty string, because an empty third field is a trailing tab and nothing else: it
|
||||
/// would be the only difference between declared and not, and it would be invisible in
|
||||
/// a terminal and in a completion alike. The placeholder is also what the file itself
|
||||
/// holds under that heading, so the field stays the section's opening line either way.
|
||||
///
|
||||
/// [`CampaignRow::summary`]: crate::tui::CampaignRow::summary
|
||||
/// [`NO_ANNOTATION`]: crate::tag::NO_ANNOTATION
|
||||
pub fn summary(&self, tag: &str) -> Option<&str> {
|
||||
let annotation = self.tags.get(tag)?;
|
||||
|
||||
Some(match annotation.lines().next() {
|
||||
Some(line) => line,
|
||||
None => NO_ANNOTATION,
|
||||
})
|
||||
}
|
||||
|
||||
/// Declare `tag`, or replace what it means.
|
||||
///
|
||||
/// One writer for both, because the file holds one section per tag either way and the
|
||||
|
||||
+2305
-312
File diff suppressed because it is too large
Load Diff
+333
-74
@@ -841,31 +841,13 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
|
||||
result.push(' ');
|
||||
result.push_str(&paint(if checked { "[x]" } else { "[ ]" }, Color::Grey, colored));
|
||||
result.push(' ');
|
||||
result.push_str(&colorize_bold(text, colored));
|
||||
result.push_str(&colorize_inline(text, colored));
|
||||
result.push('\n');
|
||||
continue;
|
||||
}
|
||||
|
||||
// Standard markdown link colorization in cyan
|
||||
if line.contains("[")
|
||||
&& line.contains("(")
|
||||
&& line.contains("]")
|
||||
&& let Some(start) = line.find("[")
|
||||
{
|
||||
let bracket_text = &line[start..];
|
||||
if let Some(end_bracket) = bracket_text.find("](") {
|
||||
let link_start = start + end_bracket + 1;
|
||||
if let Some(end) = line[link_start..].find(']') {
|
||||
let absolute_end = link_start + end + 1;
|
||||
result.push_str(&paint(&line[start..absolute_end], Color::Cyan, colored));
|
||||
result.push('\n');
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Regular content - colorize **bold** in magenta
|
||||
result.push_str(&colorize_bold(line, colored));
|
||||
// Regular content, with its inline markup coloured in place.
|
||||
result.push_str(&colorize_inline(line, colored));
|
||||
result.push('\n');
|
||||
}
|
||||
|
||||
@@ -1042,7 +1024,7 @@ fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> Strin
|
||||
// The decision this row is rendered under, not the one the terminal
|
||||
// would give: `colorize_line` asked `should_use_colors()` here, which is
|
||||
// how escapes reached the board's detail view.
|
||||
MetadataRow::Other(text) => result.push_str(&colorize_bold(text, colored)),
|
||||
MetadataRow::Other(text) => result.push_str(&colorize_inline(text, colored)),
|
||||
}
|
||||
result.push('\n');
|
||||
}
|
||||
@@ -1077,13 +1059,20 @@ pub fn is_unknown_value(value: &str) -> bool {
|
||||
trimmed == NONE || trimmed == NOT_SET
|
||||
}
|
||||
|
||||
/// Replace `**bold**` with colour, or leave the line exactly as it is.
|
||||
/// Replace `**bold**` with colour and paint `[text](url)`, or leave the line exactly
|
||||
/// as it is.
|
||||
///
|
||||
/// Taking `enabled` rather than asking makes both paths testable, and the
|
||||
/// disabled path matters: stripping the markers when there is no colour to
|
||||
/// replace them with loses the emphasis altogether, which is what happens to
|
||||
/// every piped `show` and to everything the opencode tools read.
|
||||
fn colorize_bold(line: &str, enabled: bool) -> String {
|
||||
///
|
||||
/// One walk for both markers rather than two passes. A pass over the output of
|
||||
/// another would be scanning text that already holds escape sequences, and `\x1b[36m`
|
||||
/// carries an opening bracket: a link scan run afterwards would take the escape for
|
||||
/// markup. Walking the source once is the only place either marker can be recognised
|
||||
/// for what it is.
|
||||
fn colorize_inline(line: &str, enabled: bool) -> String {
|
||||
if !enabled {
|
||||
return line.to_string();
|
||||
}
|
||||
@@ -1093,27 +1082,34 @@ fn colorize_bold(line: &str, enabled: bool) -> String {
|
||||
let mut i = 0;
|
||||
|
||||
while i < chars.len() {
|
||||
if !is_delimiter(&chars, i) {
|
||||
result.push(chars[i]);
|
||||
i += 1;
|
||||
// Unterminated markup falls through to the push below, one character at a
|
||||
// time, so the rest of the line survives as the literal text it is. The old
|
||||
// link branch pushed its match and dropped everything around it.
|
||||
if is_delimiter(&chars, i)
|
||||
&& let Some(close) = (i + 2..chars.len()).find(|&at| is_delimiter(&chars, at))
|
||||
{
|
||||
let bold: String = chars[i + 2..close].iter().collect();
|
||||
// `enabled`, not `should_use_colors()`. Asking again here made the
|
||||
// flag a lie: the early return above respected it and this did not.
|
||||
result.push_str(&paint(&bold, Color::Magenta, enabled));
|
||||
i = close + 2;
|
||||
continue;
|
||||
}
|
||||
|
||||
match (i + 2..chars.len()).find(|&at| is_delimiter(&chars, at)) {
|
||||
Some(close) => {
|
||||
let bold: String = chars[i + 2..close].iter().collect();
|
||||
// `enabled`, not `should_use_colors()`. Asking again here made the
|
||||
// flag a lie: the early return above respected it and this did not.
|
||||
result.push_str(&paint(&bold, Color::Magenta, enabled));
|
||||
i = close + 2;
|
||||
}
|
||||
// Unterminated: the rest is literal. The old scan walked off the end
|
||||
// here and dropped the final character.
|
||||
None => {
|
||||
result.extend(&chars[i..]);
|
||||
return result;
|
||||
}
|
||||
if chars[i] == '['
|
||||
&& let Some(end) = link_end(&chars, i)
|
||||
{
|
||||
// Markers and url kept, unlike the bold pair. The url is content: a
|
||||
// reader of `show` wants to see where the link goes, and the terminal
|
||||
// that would make it clickable is not something worklane can count on.
|
||||
let link: String = chars[i..end].iter().collect();
|
||||
result.push_str(&paint(&link, Color::Cyan, enabled));
|
||||
i = end;
|
||||
continue;
|
||||
}
|
||||
|
||||
result.push(chars[i]);
|
||||
i += 1;
|
||||
}
|
||||
|
||||
result
|
||||
@@ -1123,6 +1119,22 @@ fn is_delimiter(chars: &[char], at: usize) -> bool {
|
||||
chars.get(at) == Some(&'*') && chars.get(at + 1) == Some(&'*')
|
||||
}
|
||||
|
||||
/// The index one past the end of the `[text](url)` opening at `open`, or nothing when
|
||||
/// the line does not close one.
|
||||
///
|
||||
/// The closing parenthesis is what ends a link. The old branch looked for a second
|
||||
/// square bracket there, which a well-formed link does not have, so the whole branch
|
||||
/// fired only on text that was not a link at all.
|
||||
fn link_end(chars: &[char], open: usize) -> Option<usize> {
|
||||
let close_text = (open + 1..chars.len()).find(|&at| chars[at] == ']')?;
|
||||
if chars.get(close_text + 1) != Some(&'(') {
|
||||
return None;
|
||||
}
|
||||
|
||||
let close_url = (close_text + 2..chars.len()).find(|&at| chars[at] == ')')?;
|
||||
Some(close_url + 1)
|
||||
}
|
||||
|
||||
pub const METADATA_HEADING: &str = "## Metadata";
|
||||
|
||||
fn is_metadata_heading(line: &str) -> bool {
|
||||
@@ -1776,23 +1788,38 @@ fn section_body(lines: &[&str], heading: &str) -> Option<std::ops::Range<usize>>
|
||||
Some(after..section_end(lines, after))
|
||||
}
|
||||
|
||||
/// The first line of a section's body, or nothing when the section is absent or holds
|
||||
/// only its placeholder.
|
||||
/// A section's body as prose, or nothing when the section is absent or holds only its
|
||||
/// placeholder.
|
||||
///
|
||||
/// For a view with one row to spend on prose: the board's campaign frame and its picker
|
||||
/// both want the opening line of a description and have no room for the rest. Through
|
||||
/// [`section_body`] rather than a scan of its own, so what counts as the section is
|
||||
/// The whole of it, the blank lines between paragraphs included, for a view that can page
|
||||
/// through what it cannot fit: the board's campaign frame gives a description three rows
|
||||
/// and scrolls the rest, and the one line the picker draws is the first line of this.
|
||||
///
|
||||
/// It replaced `section_opening`, which did the cut here. The cut belongs to the view that
|
||||
/// wants one line, not to the read: the file is only in hand while the campaigns directory
|
||||
/// is being read, so what that read has to carry is everything a view might want, and
|
||||
/// `CampaignRow::summary` is where the one line comes off it again.
|
||||
///
|
||||
/// Through [`section_body`] rather than a scan of its own, so what counts as the section is
|
||||
/// decided in one place, and the placeholder reads as nothing here the way it does to
|
||||
/// `append`.
|
||||
pub fn section_opening(content: &str, section: &Section) -> Option<String> {
|
||||
/// `append`. Only the ends are trimmed: those blanks separate the body from its heading and
|
||||
/// from whatever follows, and a view that kept them would open on empty rows and scroll
|
||||
/// past empty ones at the end. Indentation inside a line survives, since a nested list is
|
||||
/// part of the prose.
|
||||
pub fn section_prose(content: &str, section: &Section) -> Option<String> {
|
||||
let lines: Vec<&str> = content.lines().collect();
|
||||
let body = section_body(&lines, section.heading)?;
|
||||
|
||||
lines[body]
|
||||
let kept: Vec<&str> = lines[body]
|
||||
.iter()
|
||||
.map(|line| line.trim())
|
||||
.find(|line| !line.is_empty() && *line != section.placeholder)
|
||||
.map(|line| line.to_string())
|
||||
.map(|line| line.trim_end())
|
||||
.filter(|line| *line != section.placeholder)
|
||||
.collect();
|
||||
|
||||
let start = kept.iter().position(|line| !line.is_empty())?;
|
||||
let end = kept.iter().rposition(|line| !line.is_empty())?;
|
||||
|
||||
Some(kept[start..=end].join("\n"))
|
||||
}
|
||||
|
||||
/// Where the body's content ends, ignoring the blank lines that separate it from
|
||||
@@ -1828,6 +1855,12 @@ pub fn clear_section_body(content: &str, section: &Section) -> Result<String> {
|
||||
}
|
||||
|
||||
/// The line surgery both of the above are, given a body that is already rendered.
|
||||
///
|
||||
/// The refusal names the section and not the file it is missing from, because both a ticket
|
||||
/// and a campaign reach here: `campaign set --description` writes a campaign's one prose
|
||||
/// section through this, so "Ticket has no description section" would be wrong half the
|
||||
/// time. `write_then_replace` carries the noun instead, where a message about a *file* is
|
||||
/// worth spelling.
|
||||
fn replace_section_body(
|
||||
content: &str,
|
||||
section: &Section,
|
||||
@@ -1835,7 +1868,7 @@ fn replace_section_body(
|
||||
) -> Result<String> {
|
||||
let lines: Vec<&str> = content.lines().collect();
|
||||
let body = section_body(&lines, section.heading)
|
||||
.ok_or_else(|| anyhow!("Ticket has no {} section", section.label))?;
|
||||
.ok_or_else(|| anyhow!("There is no {} section to write to", section.label))?;
|
||||
|
||||
let mut out: Vec<String> = lines[..body.start].iter().map(|l| l.to_string()).collect();
|
||||
out.extend(body_lines);
|
||||
@@ -1856,7 +1889,7 @@ fn replace_section_body(
|
||||
pub fn append_section_body(content: &str, section: &Section, items: &[String]) -> Result<String> {
|
||||
let lines: Vec<&str> = content.lines().collect();
|
||||
let body = section_body(&lines, section.heading)
|
||||
.ok_or_else(|| anyhow!("Ticket has no {} section", section.label))?;
|
||||
.ok_or_else(|| anyhow!("There is no {} section to write to", section.label))?;
|
||||
|
||||
let at = body_content_end(&lines, &body);
|
||||
let existing: Vec<&&str> = lines[body.start..at]
|
||||
@@ -3062,10 +3095,183 @@ pub fn by_status_order(status: Status, a: &TicketItem, b: &TicketItem) -> std::c
|
||||
by_stamp.then_with(|| by_priority_then_title(a, b))
|
||||
}
|
||||
|
||||
/// The environment variable that keeps a test's fixture directory on disk.
|
||||
///
|
||||
/// Opt-in rather than on-by-default-when-a-test-fails, because the assertions in this crate
|
||||
/// carry the state they are about: a failing board test prints the rendered rows, a failing
|
||||
/// listing test prints the listing. The path is what you want when you would rather poke at
|
||||
/// the files than read the message, which is the less common of the two.
|
||||
#[cfg(test)]
|
||||
pub const KEEP_FIXTURES: &str = "WORKLANE_KEEP_FIXTURES";
|
||||
|
||||
/// A fixture directory under the system temp directory that removes itself.
|
||||
///
|
||||
/// Every unit test in this crate builds its board or its status directory by hand under
|
||||
/// `std::env::temp_dir()`. The ones that remembered a `remove_dir_all` at the end of the
|
||||
/// test only cleaned up when their assertions passed, and most had no such line at all, so
|
||||
/// a full run left one directory per test behind. `/tmp` reached 18363 of them and filled
|
||||
/// the disk, which failed a link step and then a `git add` with "No space left on device" —
|
||||
/// an error that names neither the tests nor what they left behind. That is b74dc5a.
|
||||
///
|
||||
/// A `Drop` rather than a line at the end of each test, because that is the only shape that
|
||||
/// runs when an assertion fails, which is exactly when a fixture is most likely to be
|
||||
/// stranded: unwinding runs destructors, so the guard holds on the failing path without the
|
||||
/// test having to say anything.
|
||||
///
|
||||
/// `assert_fs::TempDir` is a dev-dependency already and is what the integration tests use,
|
||||
/// and it was still not the answer here. It names its directories `.tmpXXXXXX`, which says
|
||||
/// nothing about whose they are for the one case that matters — the one left on disk on
|
||||
/// purpose — and it has no opinion about naming the path when it keeps one. Wrapping it to
|
||||
/// add both is more code than this.
|
||||
///
|
||||
/// `Deref` to `Path`, so a fixture reads as the path it stands for at the call sites that
|
||||
/// already had one and nothing had to change but the type.
|
||||
#[cfg(test)]
|
||||
pub struct Fixture {
|
||||
/// What is removed: the directory this fixture created at the top.
|
||||
root: std::path::PathBuf,
|
||||
/// What the test works with, at or below the root. The two differ only for a fixture
|
||||
/// that needs a named directory inside a parent it can also throw away.
|
||||
path: std::path::PathBuf,
|
||||
/// Whether to leave the directory behind, read once here rather than at drop time.
|
||||
///
|
||||
/// At construction because the answer must not be able to change between a test
|
||||
/// starting and ending, and because it is what [`Fixture::swept`] can then turn off for
|
||||
/// the tests that are about the guard rather than about this flag.
|
||||
keep: bool,
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
impl Fixture {
|
||||
/// A fresh directory, named after the family of tests that asked for it.
|
||||
///
|
||||
/// The prefix earns its place on the kept path: `worklane-tui-` says which suite left it
|
||||
/// where a random name would not, and the uuid is what makes two fixtures with one
|
||||
/// prefix two directories, so no test can reach another's.
|
||||
pub fn new(prefix: &str) -> Self {
|
||||
let root = std::env::temp_dir().join(format!("{prefix}-{}", uuid::Uuid::new_v4()));
|
||||
std::fs::create_dir_all(&root).unwrap();
|
||||
|
||||
Fixture {
|
||||
path: root.clone(),
|
||||
root,
|
||||
keep: std::env::var_os(KEEP_FIXTURES).is_some(),
|
||||
}
|
||||
}
|
||||
|
||||
/// The same fixture, swept up whatever the environment says.
|
||||
///
|
||||
/// For the tests below, which assert that the directory goes: they are about the guard
|
||||
/// and not about the flag, so `WORKLANE_KEEP_FIXTURES` in a reader's environment must
|
||||
/// not be able to fail them.
|
||||
pub fn swept(mut self) -> Self {
|
||||
self.keep = false;
|
||||
self
|
||||
}
|
||||
|
||||
/// The same fixture, pointing at a directory inside it.
|
||||
///
|
||||
/// For the tree a project test needs: `<root>/<project>/.worklane`, where the path the
|
||||
/// test hands to `projects` is the project and what has to be removed is the root above
|
||||
/// it. Consuming, so one directory never has two guards and therefore never two attempts
|
||||
/// to remove it.
|
||||
pub fn child(mut self, name: &str) -> Self {
|
||||
self.path = self.root.join(name);
|
||||
self
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
impl AsRef<std::path::Path> for Fixture {
|
||||
fn as_ref(&self) -> &std::path::Path {
|
||||
&self.path
|
||||
}
|
||||
}
|
||||
|
||||
/// Beside `AsRef`, because the two reach different call sites: a parameter bound by
|
||||
/// `impl AsRef<Path>` is not a coercion site, and a parameter typed `&Path` is.
|
||||
#[cfg(test)]
|
||||
impl std::ops::Deref for Fixture {
|
||||
type Target = std::path::Path;
|
||||
|
||||
fn deref(&self) -> &std::path::Path {
|
||||
&self.path
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
impl Drop for Fixture {
|
||||
fn drop(&mut self) {
|
||||
if self.keep {
|
||||
// Named, since a fixture kept and not findable is a fixture kept for nothing.
|
||||
eprintln!("kept fixture {}", self.root.display());
|
||||
return;
|
||||
}
|
||||
|
||||
// Best effort. A directory that will not go must not turn a passing test into a
|
||||
// failing one, and must not panic a second time out of a drop that is already
|
||||
// unwinding, which would lose the failure the test was reporting.
|
||||
std::fs::remove_dir_all(&self.root).ok();
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// The guard removes the directory when it goes out of scope, which is what makes the
|
||||
/// cleanup independent of the assertions passing: unwinding runs destructors, so a
|
||||
/// failing test drops its fixture on the way out exactly as a passing one does.
|
||||
#[test]
|
||||
fn a_fixture_removes_itself_when_its_guard_goes() {
|
||||
let path = {
|
||||
let dir = Fixture::new("worklane-guard").swept();
|
||||
fs::write(dir.join("a.md"), "body").unwrap();
|
||||
assert!(dir.exists(), "the fixture was not created");
|
||||
dir.to_path_buf()
|
||||
};
|
||||
|
||||
assert!(!path.exists(), "the fixture outlived its guard: {}", path.display());
|
||||
}
|
||||
|
||||
/// And on the failing path, which is the whole point: a line at the end of a test does
|
||||
/// not run when an assertion above it does not pass.
|
||||
#[test]
|
||||
fn a_fixture_removes_itself_when_the_test_panics() {
|
||||
// The default hook would print this deliberate panic and make a green run read as a
|
||||
// red one. Swapped for the length of the call and put straight back, which is as
|
||||
// narrow as a process-wide hook can be made.
|
||||
let hook = std::panic::take_hook();
|
||||
std::panic::set_hook(Box::new(|_| {}));
|
||||
let caught = std::panic::catch_unwind(|| {
|
||||
let dir = Fixture::new("worklane-guard").swept();
|
||||
// Handed out through the payload, so the assertion below has a path to look at
|
||||
// whether or not the guard did its job.
|
||||
std::panic::panic_any(dir.to_path_buf());
|
||||
});
|
||||
std::panic::set_hook(hook);
|
||||
|
||||
let path = *caught
|
||||
.expect_err("the closure did not panic")
|
||||
.downcast::<std::path::PathBuf>()
|
||||
.expect("the panic did not carry the fixture path");
|
||||
|
||||
assert!(!path.exists(), "the fixture survived a failing test: {}", path.display());
|
||||
}
|
||||
|
||||
/// Two fixtures with one prefix are two directories, so no test can rely on one another
|
||||
/// test built — which the shared temp directory is what made possible.
|
||||
#[test]
|
||||
fn two_fixtures_with_one_prefix_are_two_directories() {
|
||||
let first = Fixture::new("worklane-guard");
|
||||
let second = Fixture::new("worklane-guard");
|
||||
assert_ne!(first.to_path_buf(), second.to_path_buf(), "one directory, two guards");
|
||||
|
||||
let kept = second.to_path_buf();
|
||||
drop(first);
|
||||
assert!(kept.exists(), "one fixture going took the other with it");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn no_color_disables_colour_on_a_terminal() {
|
||||
assert!(!colors_wanted(true, Some("1"), Some("xterm-256color")));
|
||||
@@ -3439,8 +3645,7 @@ mod tests {
|
||||
/// in `show`, so the two cannot disagree about what a criterion is.
|
||||
#[test]
|
||||
fn collect_ticket_items_counts_the_criteria_show_would_number() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-count-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
let dir = Fixture::new("worklane-count");
|
||||
|
||||
let write = |name: &str, body: &str| {
|
||||
fs::write(
|
||||
@@ -3465,8 +3670,6 @@ mod tests {
|
||||
counted.contains(&None),
|
||||
"a ticket with no criteria got a count: {counted:?}"
|
||||
);
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// The count is a directory listing rather than a read: nothing here parses a comment,
|
||||
@@ -3522,8 +3725,7 @@ mod tests {
|
||||
/// listing that stops on one malformed ticket is the worse failure.
|
||||
#[test]
|
||||
fn collect_ticket_items_reads_the_uuid_and_the_blockers_it_records() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-blocked-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
let dir = Fixture::new("worklane-blocked");
|
||||
|
||||
let uuid = |tail: &str| format!("11111111-0000-4000-8000-00000000000{tail}");
|
||||
let write = |name: &str, relations: &str| {
|
||||
@@ -3548,8 +3750,6 @@ mod tests {
|
||||
assert_eq!(of("T1").blockers, vec![uuid("2")]);
|
||||
assert!(of("T2").blockers.is_empty(), "a regression was read as a blocker");
|
||||
assert!(of("T3").blockers.is_empty(), "an unreadable section was not survived");
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// Whole values, so a filter or a card cannot confuse two tags that share a prefix.
|
||||
@@ -3576,8 +3776,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn collect_ticket_items_lists_only_md_files() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-stray-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
let dir = Fixture::new("worklane-stray");
|
||||
|
||||
fs::write(
|
||||
dir.join("11111111-0000-4000-8000-000000000001.md"),
|
||||
@@ -3593,8 +3792,6 @@ mod tests {
|
||||
let titles: Vec<&str> = items.iter().map(|item| item.title.as_str()).collect();
|
||||
|
||||
assert_eq!(titles, vec!["Real"], "{titles:?}");
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// The template ticket, and the shape every insertion test measures against.
|
||||
@@ -3912,8 +4109,7 @@ mod tests {
|
||||
/// comparison time, which is what makes an ordered column cost one read per file.
|
||||
#[test]
|
||||
fn collect_ticket_items_reads_the_stamps_the_order_sorts_on() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-stamps-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
let dir = Fixture::new("worklane-stamps");
|
||||
|
||||
fs::write(
|
||||
dir.join("aaaa_walked.md"),
|
||||
@@ -3944,8 +4140,6 @@ mod tests {
|
||||
assert_eq!(fresh.committed_on, None);
|
||||
assert_eq!(fresh.submitted_on, None);
|
||||
assert_eq!(fresh.completed_on, None);
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// Removal is scoped to the section for the same reason the write is: a description
|
||||
@@ -4377,12 +4571,12 @@ mod tests {
|
||||
#[test]
|
||||
fn bold_markers_survive_when_colour_is_off() {
|
||||
let line = "Some **bold** text";
|
||||
assert_eq!(colorize_bold(line, false), line);
|
||||
assert_eq!(colorize_inline(line, false), line);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bold_markers_are_replaced_when_colour_is_on() {
|
||||
let out = colorize_bold("Some **bold** text", true);
|
||||
let out = colorize_inline("Some **bold** text", true);
|
||||
assert!(out.contains("bold"), "was {out:?}");
|
||||
assert!(!out.contains("**"), "markers left behind in {out:?}");
|
||||
}
|
||||
@@ -4391,17 +4585,82 @@ mod tests {
|
||||
#[test]
|
||||
fn an_unterminated_marker_keeps_the_whole_line() {
|
||||
for line in ["a **bold", "**", "***", "trailing **"] {
|
||||
assert_eq!(colorize_bold(line, true), line, "for {line:?}");
|
||||
assert_eq!(colorize_inline(line, true), line, "for {line:?}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn several_bold_runs_on_one_line_all_survive() {
|
||||
let out = colorize_bold("**one** and **two** and rest", true);
|
||||
let out = colorize_inline("**one** and **two** and rest", true);
|
||||
assert!(out.contains("one") && out.contains("two") && out.ends_with("and rest"));
|
||||
assert!(!out.contains("**"), "was {out:?}");
|
||||
}
|
||||
|
||||
/// The old branch pushed the span it matched and dropped the rest of the line.
|
||||
#[test]
|
||||
fn a_link_keeps_the_text_on_either_side_of_it() {
|
||||
let out = colorize_inline("see [the docs](https://x.test/y) for more", true);
|
||||
|
||||
assert!(out.starts_with("see "), "was {out:?}");
|
||||
assert!(out.ends_with(" for more"), "was {out:?}");
|
||||
assert!(out.contains("[the docs](https://x.test/y)"), "was {out:?}");
|
||||
assert!(out.contains(Color::Cyan.ansi()), "not painted in {out:?}");
|
||||
}
|
||||
|
||||
/// With no colour to carry it, the markup is the markup.
|
||||
#[test]
|
||||
fn a_link_survives_unchanged_when_colour_is_off() {
|
||||
let line = "see [the docs](https://x.test/y) for more";
|
||||
assert_eq!(colorize_inline(line, false), line);
|
||||
}
|
||||
|
||||
/// The closing parenthesis ends a link. Looking for a second square bracket there,
|
||||
/// as the old branch did, meant it fired on anything but a link.
|
||||
#[test]
|
||||
fn text_that_is_not_a_closed_link_is_left_alone() {
|
||||
for line in [
|
||||
"a [label] and (a note)",
|
||||
"unterminated [text](http://x.test",
|
||||
"[a][b] reference style",
|
||||
"bare [",
|
||||
] {
|
||||
assert_eq!(colorize_inline(line, true), line, "for {line:?}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn several_links_on_one_line_all_survive() {
|
||||
let out = colorize_inline("[a](1) then [b](2) then end", true);
|
||||
|
||||
assert!(out.contains("[a](1)") && out.contains("[b](2)"), "was {out:?}");
|
||||
assert!(out.ends_with(" then end"), "was {out:?}");
|
||||
}
|
||||
|
||||
/// Both markers are recognised in the same walk, so a line does not have to pick
|
||||
/// which of the two it gets.
|
||||
#[test]
|
||||
fn bold_and_a_link_on_one_line_are_both_coloured() {
|
||||
let out = colorize_inline("**note**: read [this](http://x.test) first", true);
|
||||
|
||||
assert!(!out.contains("**"), "markers left behind in {out:?}");
|
||||
assert!(out.contains("[this](http://x.test)"), "was {out:?}");
|
||||
assert!(out.contains(Color::Magenta.ansi()), "no bold in {out:?}");
|
||||
assert!(out.contains(Color::Cyan.ansi()), "no link in {out:?}");
|
||||
assert!(out.ends_with(" first"), "was {out:?}");
|
||||
}
|
||||
|
||||
/// End to end: the body a `show` prints keeps every word of a line with a link.
|
||||
#[test]
|
||||
fn a_body_line_with_a_link_keeps_all_of_its_text() {
|
||||
let content = "# T\n\n## Description\n\nbefore [docs](http://x.test/a) after\n";
|
||||
let rendered = content_trim(content, false, &Resolved::default());
|
||||
|
||||
assert!(
|
||||
rendered.ends_with("before [docs](http://x.test/a) after\n"),
|
||||
"{rendered:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn short_id_shortens_a_full_uuid() {
|
||||
assert_eq!(short_id("c230d2c6-d78a-44a5-8f5f-88fb28f84493"), "c230d2c");
|
||||
|
||||
+445
-5
@@ -1129,11 +1129,13 @@ fn an_unknown_campaign_is_refused_and_nothing_is_written() {
|
||||
);
|
||||
}
|
||||
|
||||
/// No `--description`: `set` and `append` are a pair for a prose section, and a way to
|
||||
/// replace a description with no way to add a paragraph is half of it. Pinned so the
|
||||
/// omission stays a decision rather than becoming an oversight somebody fills in.
|
||||
/// `--description` arrived with `campaign append`, 32e98ab, because for a prose section the
|
||||
/// two are a pair. What is still deliberately absent is what this pins: no `--owner`, which
|
||||
/// would settle by accident whether `chown` grows a campaign, and no `--clear`, because a
|
||||
/// campaign's description has no cleared form and `Clearable`'s variants are a ticket's
|
||||
/// fields.
|
||||
#[test]
|
||||
fn campaign_set_offers_no_description_and_no_owner() {
|
||||
fn campaign_set_offers_no_owner_and_no_clear() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
@@ -1142,7 +1144,7 @@ fn campaign_set_offers_no_description_and_no_owner() {
|
||||
|
||||
assert!(help.contains("--codename"), "{help}");
|
||||
assert!(help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--description"), "{help}");
|
||||
assert!(help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--owner"), "{help}");
|
||||
assert!(!help.contains("--clear"), "{help}");
|
||||
}
|
||||
@@ -1263,3 +1265,441 @@ fn the_title_is_replaced_without_force() {
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n"));
|
||||
}
|
||||
|
||||
// ---------------------------------------------- campaign set --description --
|
||||
|
||||
/// The point of 32e98ab: the description a campaign was filed with is no longer the one it
|
||||
/// keeps. `create_campaign` writes prose, so this is a replacement rather than a first line.
|
||||
#[test]
|
||||
fn campaign_set_replaces_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"--description",
|
||||
"What the tag has to hold.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Updated description"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("What the tag has to hold."), "{content}");
|
||||
assert!(
|
||||
!content.contains("What has to ship together."),
|
||||
"the old description survived: {content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// An empty value between two others is the paragraph break, the rule every prose argument
|
||||
/// in the tool follows: `add --description`, `set --description` and `tags --annotation`.
|
||||
#[test]
|
||||
fn an_empty_value_is_a_paragraph_break_in_a_campaigns_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"The tag itself.",
|
||||
"-d",
|
||||
"",
|
||||
"-d",
|
||||
"And what blocks it.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("The tag itself.\n\nAnd what blocks it."), "{content}");
|
||||
}
|
||||
|
||||
/// And an all-blank value is refused rather than emptying the section. The refusal names no
|
||||
/// flag, because there is none: a campaign's description has no cleared form, which is the
|
||||
/// `Clearable` question 32e98ab settled rather than deferred.
|
||||
#[test]
|
||||
fn an_all_blank_description_is_refused_and_names_no_clear_flag() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "-d", "", "-d", " "]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
assert!(said.contains("An empty value is a paragraph break"), "{said}");
|
||||
assert!(said.contains("no cleared form"), "{said}");
|
||||
assert!(!said.contains("--clear"), "it named a flag that does not exist: {said}");
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
|
||||
}
|
||||
|
||||
/// The whole-file comparison `set`, `chown` and the codename already use, so a description
|
||||
/// replaced with the one it already holds writes nothing.
|
||||
#[test]
|
||||
fn setting_the_description_a_campaign_already_has_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"What has to ship together.",
|
||||
],
|
||||
);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was rewritten");
|
||||
}
|
||||
|
||||
/// Three fields in one call, since the group is `multiple` and the description is in it.
|
||||
#[test]
|
||||
fn campaign_set_takes_the_title_the_description_and_the_codename_together() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-t",
|
||||
"First public release",
|
||||
"-d",
|
||||
"What the tag has to hold.",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("title, description, codename"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.starts_with("# First public release\n"), "{content}");
|
||||
assert!(content.contains("What the tag has to hold."), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
}
|
||||
|
||||
/// A refused codename takes the description down with it, the way it already takes the
|
||||
/// title: checked before any edit is applied, so a call writes all of what it asked for or
|
||||
/// none of it.
|
||||
#[test]
|
||||
fn a_refused_codename_takes_the_description_down_with_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1",
|
||||
"-d",
|
||||
"Rewritten anyway.",
|
||||
"-c",
|
||||
"beaver",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the description went through");
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------- campaign append --
|
||||
|
||||
/// The other half of the pair, and the reason `set --description` is not a flag on its own:
|
||||
/// adding a line to a description must not mean retyping the rest of it.
|
||||
#[test]
|
||||
fn campaign_append_adds_a_paragraph_without_replacing_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"And what is out of scope.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Appended to description"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
// The paragraph lands after the one that was there, with the blank line between them
|
||||
// that makes it a paragraph rather than a run-on.
|
||||
assert!(
|
||||
content.contains("What has to ship together.\n\nAnd what is out of scope.\n"),
|
||||
"{content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Several values in one call are lines *within* the paragraph, not several paragraphs. The
|
||||
/// same reading `append --description` gives a ticket, since it is the same section entry.
|
||||
#[test]
|
||||
fn the_values_of_one_append_are_lines_within_the_paragraph() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"Out of scope:",
|
||||
"-d",
|
||||
"the installer.",
|
||||
],
|
||||
);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("Out of scope:\nthe installer.\n"), "{content}");
|
||||
}
|
||||
|
||||
/// A campaign filed with no description holds the placeholder, and appending replaces it
|
||||
/// rather than following it: the alternative reads `_No description provided._` above the
|
||||
/// description. `append_section_body`'s rule, so nothing here handles the case.
|
||||
#[test]
|
||||
fn appending_to_an_empty_description_replaces_the_placeholder() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "add", "--title", "No prose yet"]);
|
||||
|
||||
let uuid = {
|
||||
let names = campaigns(&worklane);
|
||||
let name = names
|
||||
.iter()
|
||||
.find(|name| name.ends_with("_no-prose-yet.md"))
|
||||
.expect("the campaign was not filed");
|
||||
name.split('_').next().unwrap().to_string()
|
||||
};
|
||||
assert!(
|
||||
campaign_file(&worklane, &uuid).contains("_No description provided._"),
|
||||
"the placeholder is not what add writes any more"
|
||||
);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"No prose yet",
|
||||
"-d",
|
||||
"The first thing said.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let content = campaign_file(&worklane, &uuid);
|
||||
assert!(content.contains("The first thing said."), "{content}");
|
||||
assert!(
|
||||
!content.contains("_No description provided._"),
|
||||
"the placeholder is still above the description: {content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Every value blank is refused rather than writing nothing quietly, the answer `append`
|
||||
/// gives a ticket, in the same words: appending nothing was never a way to empty anything,
|
||||
/// so there is no flag to name.
|
||||
#[test]
|
||||
fn an_all_blank_append_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "v1 release", "-d", " "]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("Nothing to append"), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
|
||||
}
|
||||
|
||||
/// A bare `campaign append <campaign>` is a usage error rather than a silent no-op, the way
|
||||
/// a bare `campaign set` is. `--description` is `required` rather than a group of one.
|
||||
#[test]
|
||||
fn campaign_append_with_no_description_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "v1 release"]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
|
||||
}
|
||||
|
||||
/// Appending to a scalar has no meaning, which is the line `append` already draws for a
|
||||
/// ticket: no `--title` there and none here, and no `--codename` either.
|
||||
#[test]
|
||||
fn campaign_append_offers_only_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "--help"]);
|
||||
let help = stdout(&out);
|
||||
|
||||
assert!(help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--codename"), "{help}");
|
||||
assert!(!help.contains("--force"), "{help}");
|
||||
}
|
||||
|
||||
/// A campaign is addressed here by the same tiers everything else takes, codename included,
|
||||
/// because it goes through `resolve_campaign` rather than a lookup of its own.
|
||||
#[test]
|
||||
fn campaign_append_resolves_the_campaign_by_its_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "beaver"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "beaver", "-d", "One more thing."]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
campaign_file(&worklane, CAMP_A).contains("One more thing."),
|
||||
"{}",
|
||||
campaign_file(&worklane, CAMP_A)
|
||||
);
|
||||
}
|
||||
|
||||
/// An unknown campaign leaves every campaign alone, the answer `campaign set` and `assign`
|
||||
/// already give.
|
||||
#[test]
|
||||
fn campaign_append_refuses_an_unknown_campaign() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "nothing-by-that-name", "-d", "Text."]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("No campaign found"), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
|
||||
}
|
||||
|
||||
// ------------------------------------------------------ the shared machinery --
|
||||
|
||||
/// A campaign has one section where a ticket has four, and the section table in `util.rs` is
|
||||
/// what both go through. So the surgery has to land against `## Metadata`, which is the only
|
||||
/// heading that follows a campaign's description, and leave everything outside the body
|
||||
/// alone: a handwritten section, the owner, and the codename in its place.
|
||||
#[test]
|
||||
fn the_description_is_edited_in_place_in_a_file_with_one_section() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let original = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
original.replace("## Metadata", "## Notes\nA handwritten note.\n\n## Metadata"),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
run(&temp, &["campaign", "set", "v1", "-d", "Replaced."]);
|
||||
run(&temp, &["campaign", "append", "v1", "-d", "Added."]);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("## Description\nReplaced.\n\nAdded.\n"), "{content}");
|
||||
// Nothing outside the body moved: the section that follows it, the handwritten one
|
||||
// between them, and the fields under it.
|
||||
assert!(content.contains("## Notes\nA handwritten note."), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
assert!(content.contains("- **Owner**: alice"), "{content}");
|
||||
assert!(!content.contains("**Status**"), "a status was invented: {content}");
|
||||
// And no section a campaign does not have was inserted to anchor against.
|
||||
assert!(!content.contains("## Acceptance Criteria"), "{content}");
|
||||
assert!(!content.contains("## Implementation Plan"), "{content}");
|
||||
}
|
||||
|
||||
/// The heading is the one in the section table, so `campaign set --description` reaches the
|
||||
/// section `campaign_body` wrote and `campaign show` prints. A second spelling scoped to
|
||||
/// campaigns is what this would catch.
|
||||
#[test]
|
||||
fn the_description_a_campaign_is_filed_with_is_the_one_set_replaces() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"Filed with prose",
|
||||
"--description",
|
||||
"As filed.",
|
||||
],
|
||||
);
|
||||
run(&temp, &["campaign", "set", "Filed with prose", "-d", "As replaced."]);
|
||||
|
||||
let out = run(&temp, &["campaign", "show", "Filed with prose"]);
|
||||
let shown = stdout(&out);
|
||||
assert!(shown.contains("As replaced."), "{shown}");
|
||||
assert!(!shown.contains("As filed."), "{shown}");
|
||||
// One Description heading in the file, not a second one written beside it.
|
||||
let names = campaigns(&worklane);
|
||||
let name = names
|
||||
.iter()
|
||||
.find(|name| name.ends_with("_filed-with-prose.md"))
|
||||
.expect("not filed");
|
||||
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
|
||||
assert_eq!(content.matches("## Description").count(), 1, "{content}");
|
||||
}
|
||||
|
||||
/// A campaign file with no Description heading is refused rather than given one back. Every
|
||||
/// campaign the tool files carries the heading, so an insertion path here would be reachable
|
||||
/// only from a hand-edited file, which is the opposite of the Relations case. The message
|
||||
/// names the section and not the object, because both a ticket and a campaign reach it.
|
||||
#[test]
|
||||
fn a_campaign_with_no_description_section_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let original = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
original.replace("## Description\nWhat has to ship together.\n\n", ""),
|
||||
)
|
||||
.unwrap();
|
||||
let before = fs::read_to_string(&path).unwrap();
|
||||
|
||||
for args in [
|
||||
["campaign", "set", "v1 release", "-d", "Text."],
|
||||
["campaign", "append", "v1 release", "-d", "Text."],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
assert!(said.contains("no description section"), "{said}");
|
||||
assert!(!said.contains("Ticket"), "a campaign was called a ticket: {said}");
|
||||
assert_eq!(fs::read_to_string(&path).unwrap(), before, "the file was written");
|
||||
}
|
||||
}
|
||||
|
||||
+109
-11
@@ -5,10 +5,11 @@
|
||||
//! under test are the ones that question needs: every status counted, case kept apart,
|
||||
//! alphabetical order, and an output a shell can parse.
|
||||
//!
|
||||
//! `tags add` is the other half of the same question. The listing reports the vocabulary
|
||||
//! the tickets *carry*; the file reports the one the board *intends*, and the tests below
|
||||
//! are mostly about the two being allowed to disagree without either one damaging the
|
||||
//! other.
|
||||
//! `tags add` is the other half of the same question. The file reports the vocabulary the
|
||||
//! board *intends* and the tickets carry the one it *has*, and the tests below are mostly
|
||||
//! about the two being allowed to disagree without either one damaging the other. The
|
||||
//! listing reports both and marks which is which, so the tests for the output shape are
|
||||
//! about the marking: which field it lands in, and what a board with no file still prints.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
@@ -380,19 +381,113 @@ fn a_vocabulary_that_cannot_be_read_is_refused_rather_than_replaced() {
|
||||
assert!(stray.is_empty(), "a temp file was left in .worklane");
|
||||
}
|
||||
|
||||
/// The vocabulary does not touch the listing, which counts tickets. The two disagreeing is
|
||||
/// the normal state and the thing the file is for.
|
||||
/// The listing is the union of the two vocabularies, and the two disagreeing is the normal
|
||||
/// state rather than a fault: a declaration tags no ticket, and tagging a ticket declares
|
||||
/// nothing.
|
||||
///
|
||||
/// Both halves of the disagreement in one assertion, since neither is legible without the
|
||||
/// other. `chore` is declared and carried by nothing, so it lists at zero with what it
|
||||
/// means; `bug` is carried and declared by nothing, so it lists with a count and no third
|
||||
/// field at all.
|
||||
#[test]
|
||||
fn a_declared_tag_is_not_a_carried_one() {
|
||||
fn the_listing_is_the_union_of_the_declared_and_the_carried() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
run(&temp, &["tags", "add", "chore", "-a", "Housekeeping."]);
|
||||
|
||||
// `chore` is declared and carried by nothing, `bug` is carried and declared by nothing,
|
||||
// and the listing still answers only the second question. Reporting both is 9564ac9.
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
assert_eq!(tags(&temp), vec!["bug\t1", "chore\t0\tHousekeeping."]);
|
||||
}
|
||||
|
||||
/// The third field is the annotation's *opening* line. An annotation is prose with
|
||||
/// paragraphs in it, and a second line in this output would be read as a second tag.
|
||||
#[test]
|
||||
fn the_annotation_is_cut_to_its_opening_line() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"add",
|
||||
"bug",
|
||||
"-a",
|
||||
"What it is.",
|
||||
"-a",
|
||||
"",
|
||||
"-a",
|
||||
"When to use it.",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t0\tWhat it is."]);
|
||||
}
|
||||
|
||||
/// A tag declared with nothing said about it still carries a third field, and it is the
|
||||
/// placeholder the file itself holds under that heading.
|
||||
///
|
||||
/// The subtle case, and the reason the field is not simply left empty: an empty third field
|
||||
/// is a trailing tab, so the only difference between a declared tag and an undeclared one
|
||||
/// would be invisible in a terminal and in a completion alike.
|
||||
#[test]
|
||||
fn a_tag_declared_without_an_annotation_is_still_marked_as_declared() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "carried");
|
||||
|
||||
run(&temp, &["tags", "add", "declared"]);
|
||||
|
||||
assert_eq!(tags(&temp), vec!["carried\t1", "declared\t0\t_No annotation provided._"]);
|
||||
}
|
||||
|
||||
/// `cut -f1` over the listing yields exactly the tag values, undeclared ones included.
|
||||
///
|
||||
/// The constraint the whole output shape is built around: whatever marks a carried but
|
||||
/// undeclared tag must stay out of the first field, or a completion offers a tag that does
|
||||
/// not exist and `ls --tag` comes back empty for it.
|
||||
#[test]
|
||||
fn the_first_field_is_the_bare_tag_whether_it_is_declared_or_not() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "carried,both");
|
||||
run(&temp, &["tags", "add", "both", "-a", "Carried and declared."]);
|
||||
run(&temp, &["tags", "add", "declared", "-a", "Declared only."]);
|
||||
|
||||
let first: Vec<String> = tags(&temp)
|
||||
.iter()
|
||||
.map(|line| line.split('\t').next().unwrap().to_string())
|
||||
.collect();
|
||||
assert_eq!(first, vec!["both", "carried", "declared"]);
|
||||
|
||||
// And each of them is a value `--tag` can match, which is what the first field is for.
|
||||
for tag in ["both", "carried"] {
|
||||
let out = run(&temp, &["ls", "--tag", tag, "--ids"]);
|
||||
assert_eq!(
|
||||
String::from_utf8_lossy(&out.stdout).lines().count(),
|
||||
1,
|
||||
"--tag {tag} matched nothing"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// A board with no vocabulary lists what it listed before the file existed, byte for byte.
|
||||
///
|
||||
/// Every tag on such a board is carried and undeclared, so the absence of the third field
|
||||
/// is what keeps the old output shape: a marker in it would have changed every line of
|
||||
/// every board that predates the file, and the shipped fish completion of an older version
|
||||
/// is still reading this.
|
||||
#[test]
|
||||
fn a_board_with_no_vocabulary_lists_what_it_listed_before_the_file_existed() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
|
||||
create_ticket(&worklane, "done", "22222222", "bug");
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
|
||||
let out = run(&temp, &["tags"]);
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout), "bug\t2\ncli\t1\n");
|
||||
}
|
||||
|
||||
/// The bare form is the listing, byte for byte, because the shipped fish completion calls it
|
||||
@@ -409,7 +504,10 @@ fn the_bare_form_and_ls_are_the_same_listing() {
|
||||
|
||||
assert!(bare.status.success());
|
||||
assert_eq!(bare.stdout, group.stdout);
|
||||
assert_eq!(String::from_utf8_lossy(&bare.stdout), "bug\t1\ncli\t1\n");
|
||||
assert_eq!(
|
||||
String::from_utf8_lossy(&bare.stdout),
|
||||
"bug\t1\nchore\t0\t_No annotation provided._\ncli\t1\n"
|
||||
);
|
||||
}
|
||||
|
||||
// -------------------------------------------------- changing what a tag means --
|
||||
|
||||
Reference in New Issue
Block a user