Compare commits

...
4 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 af1ef1f97f (ebad2fa) Scroll the campaign description in the frame above the board
The frame showed the opening line of a description and the rest was only
readable through `campaign show`, which means leaving the board. It now
holds three rows of prose and pages through the remainder on `pgup` and
`pgdn`, reached by going up past the top card of a column.

Four decisions rather than four edits:

`section_prose` replaces `section_opening`. The campaign file is only in
hand while the campaigns directory is being read, so that read carries
the whole description and `CampaignRow::summary` takes the picker's one
line back off it. Two fields, one cut from the other, would be two
strings free to come from different reads of the same file.

`CAMPAIGN_PROSE_ROWS` is a constant. Fitting the frame to the
description would resize every column whenever the filter changed, so
the height is fixed at three rows and scrolling covers the rest. Two
more rows of cards spent than the one row cost.

`Focus` is the third place the selection can be, held on `Tab` beside
the filter and the new `frame_offset`. Every key that acts on a card
answers for it: `enter` is inert because `Tab::selected` hands back
nothing there, `left` and `right` are inert because the frame spans the
board, and `y` copies the campaign's short id, so `y copy id` means the
id of the selected thing in every state. No card is drawn reversed while
the frame holds the selection, since that highlight is what says which
ticket a key is about. The frame is out of reach from under an open
ticket, where up and down step through tickets and the overlay follows.

`Board::scroll_page` holds the precedence, not the `main.rs` arm: an
open ticket keeps both keys whatever holds the selection behind it, the
rule `dismiss` follows for the same reason. The page indicator, the
step and the clamp are the overlay's `page_indicator`, `scroll_step` and
`last_offset`, so the two places a reader presses these keys behave the
same. The indicator sits beside `q board` rather than up beside the
title, which would shorten a long campaign name whenever its
description grew.

Criterion 11 is not done: 2a83bd4 has not landed, so there is no tag
frame to give the same treatment. The model it inherits is in place and
named on the ticket.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 17:47:09 +02:00
Ansho ReiandClaude Opus 5 8e2ab6332c (8c8a520) Ship a board administration skill, and bump to 0.26.1
Three skills taught the CLI, the review and the grooming sweep. Nothing taught
the board itself, and two jobs fell in the gap: deciding what the tags are, now
that `tags add` and `tags set` exist to declare them, and putting a board back
together when its files and fields disagree.

`worklane-admin` is the fourth. It is the one asset written to hold for a board
that tracks no software, since a vocabulary skill built around `bug` and `cli`
teaches nothing to a board tracking a household, so its worked examples span a
tool, a product strategy and a house. Tags as axes rather than as a pile of
words, what an annotation has to say to stop drift, which is the boundary
against the neighbouring tag and not the definition, and the fact that renaming
a tag means rewriting the Tags field of every ticket carrying it.

The repairs are by symptom and every one was run against a scratch board
rather than reasoned from the source, which is what the ticket demanded and
what turned up the one that matters: a ticket whose file sits in `done` while
its Status field says `backlog` cannot be repaired by one `mv`, because `mv`
reads the current status from the directory and refuses the target it is
already in. Two moves fix it. That is 7f772a7. Verifying also turned up that
nothing removes a relation, 8556048.

The line against `worklane-plan` is drawn in both documents: this one decides
the vocabulary, that one applies it across tickets.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 16:24:38 +02:00
Ansho ReiandClaude Opus 5 239d951b8c (9688d34) Add tags set, and bump to 0.26.0
A tag declared with the wrong annotation was stuck with it, which is 32e98ab's
hole arriving before the writer rather than after. The campaigns entry on this
board was already in that state: it reserved the singular for the campaign
command, and stopped being true the moment that tag was rolled in.

`worklane tags set <tag> --annotation` replaces the whole annotation.
`--annotation` is required, so a bare call is a usage error rather than a
silent no-op, and an empty one writes the placeholder, which is why there is
no `--clear`. `add` and `set` refuse what the other is for, each naming the
other, so which one wrote a line is never a question of which was typed.

No `--force`: a codename is guarded because a campaign is addressed by it,
where an annotation is prose written to be revised. No rename: the tag is the
key, so changing it means rewriting the Tags field of every ticket carrying
it.

`report` grew `report_in`, which takes the colour. `report` paints its subject
green and green means title, so a tag could not reuse it: a tag is drawn in a
`TAG_COLORS` slot or it is drawn wrong. Same wording, decision passed in,
which is the trade `paint` makes with `color_text`.

The no-op compares the rendered file rather than the annotation, the way
`apply` compares content for a ticket field.

`tags set` takes a tag the board already has, so it joins the new
`TAG_NESTED_COMMANDS` and gets a fish rule offering `worklane tags`; `tags
add` stays ruleless in `TAG_NEW_COMMANDS`. The guard now names both lists, so
the next tag positional has to pick one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 16:09:03 +02:00
Ansho ReiandClaude Opus 5 f515d69930 (1db02e5) Give the board a tags file, and bump to 0.25.0
The board carried twenty-four tags and defined none of them. `campaign` and
`campaigns` were both on it, one ticket each side, and nothing on disk could
have caught that.

`.worklane/tags.md` is the vocabulary: one level-two heading per tag, its
annotation as the prose under it, alphabetical by byte so a near-duplicate
lands next to what it duplicates. `worklane tags add <tag> --annotation`
writes it, `init` creates it empty, and `tags add` creates it on demand for a
board that predates it.

Declaring a tag tags no ticket, and tagging a ticket declares nothing. The
counts stay derived from the status directories, so the file and the board can
disagree; reporting that disagreement is 9564ac9.

`tags` becomes a group with an optional subcommand. The bare form is still the
listing, byte for byte, because the shipped fish completion calls it that way
to fill in `ls --tag`; `tags ls` is the same arm.

Every write re-renders the whole file from the parsed vocabulary rather than
splicing one section, which is why an unreadable file is an error in
`TagIndex::load` where an unreadable campaigns directory is an empty index:
empty here would mean erased.

`no_tag_taking_option_is_missing` used to panic on any tag positional. It now
allows what `TAG_NEW_COMMANDS` records, which is `tags add` alone: the tag it
takes does not exist yet, so completing it from `worklane tags` would offer
exactly the values it refuses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 15:47:05 +02:00
15 changed files with 2284 additions and 87 deletions
+11 -2
View File
@@ -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`
@@ -198,6 +199,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 +235,18 @@ 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 is `Chrome::CAMPAIGN_ROWS` 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 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 a constant, not 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 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, and the answer for `enter` falls out of this rather than being written into the dispatch. `←→` 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
- **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`, the two scroll keys and `y copy id`, and leaves out `enter` and `←→` because they do nothing there. `↑ 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
- **`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
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.24.2"
version = "0.26.2"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.24.2"
version = "0.26.2"
edition = "2024"
[dependencies]
+2 -2
View File
@@ -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 and down returns to the column it came from. 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 |
@@ -25,7 +25,7 @@ Worklane is a local Kanban flow for agentic software development.
| `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
+318
View File
@@ -0,0 +1,318 @@
---
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 carried, with counts
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: `worklane tags` counts 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.
### 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.
- `worklane tags` counts tickets, so a tag you have declared and never applied does not
appear in it. 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.
+11
View File
@@ -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:
@@ -199,6 +207,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.
+128 -3
View File
@@ -130,6 +130,56 @@ fn codename(raw: &str) -> Result<String, String> {
Ok(value)
}
/// Reject a tag value that `ls --tag` could never match.
///
/// `--tag` matches a whole value of the comma-separated Tags field, so a value carrying a
/// comma is two tags and would be declared under a name nothing can be filtered by. A line
/// break is refused for the file's sake rather than the filter's: a tag is a heading in
/// `tags.md`, and a heading is one line.
///
/// Trimmed rather than refused for surrounding space, because `parse_tags` trims every
/// value it reads off a ticket and [`TagIndex::parse`] trims every heading it reads off the
/// vocabulary. Refusing here would refuse a value that both of those accept.
///
/// [`TagIndex::parse`]: crate::tag::TagIndex::parse
fn tag_value(raw: &str) -> Result<String, String> {
let value = raw.trim();
if value.is_empty() {
return Err("tag cannot be empty".to_string());
}
if value.contains(',') {
return Err(
"tag cannot contain a comma, which is what separates one tag from the next".to_string()
);
}
if value.contains(['\n', '\r']) {
return Err("tag must be a single line".to_string());
}
Ok(value.to_string())
}
/// Reject an annotation line that would be read back as a tag of its own.
///
/// The vocabulary is one heading per tag with its prose under it, so a line of prose
/// starting with the section marker would split the annotation and declare whatever
/// followed. Refused at parse time, where nothing has been written, rather than escaped on
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking for
/// a different line.
fn annotation_line(raw: &str) -> Result<String, String> {
match raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
true => Err(format!(
"an annotation line cannot start with '{}', which is how the vocabulary file \
starts a tag",
crate::tag::SECTION
)),
false => Ok(raw.to_string()),
}
}
/// Arguments that carry prose, and therefore have to accept a value starting with
/// a hyphen.
///
@@ -244,15 +294,18 @@ pub enum Command {
ticket: String,
},
/// List the tags the board carries, and how many tickets carry each
/// The tag vocabulary: what the board carries, and what each tag means
///
/// A command rather than a mode on `ls`, for two reasons. `ls --tag <tag>` answers
/// "what is tagged bug" and cannot answer "what tags exist", which is the question a
/// grooming sweep starts from; and a `--tags` beside a `--tag` is one letter away from
/// a filter that means something else.
///
/// The output is machine-readable, like `ls --ids`: the tag, a tab, the count.
Tags,
/// The listing is machine-readable, like `ls --ids`: the tag, a tab, the count.
Tags {
#[command(subcommand)]
command: Option<TagCommand>,
},
/// Print a shell completion script
///
@@ -429,6 +482,78 @@ pub struct CampaignAddArgs {
pub owner: Option<String>,
}
/// What the tag vocabulary can be asked for.
///
/// Optional, unlike [`CampaignCommand`], and that is the whole shape of the compatibility
/// here: `worklane tags` was the listing before it was a group, the shipped fish completion
/// calls it that way to fill in `ls --tag`, and a bare call turning into a usage error would
/// break a script for the sake of symmetry. So the bare form stays the listing, and `tags
/// ls` is the same thing spelled the way `campaign ls` is.
///
#[derive(clap::Subcommand)]
pub enum TagCommand {
/// Declare a tag, and what it means
Add(TagAddArgs),
/// Replace what a declared tag means
Set(TagSetArgs),
/// List the tags the board carries, and how many tickets carry each
Ls,
}
/// What declaring a tag takes: the tag, and what it is for.
///
/// No owner and no timestamp, which every other file under `.worklane/` carries. A tag is
/// not an object with a history, it is a word the board agrees on, and `git log` over
/// `tags.md` answers who wrote which line better than a field would.
#[derive(clap::Args)]
pub struct TagAddArgs {
/// The tag to declare, spelled the way `ls --tag` matches it
#[arg(value_parser = tag_value)]
pub tag: String,
/// What the tag means and when it is appropriate. Use multiple flags for multiline
/// annotations
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = annotation_line)]
pub annotation: Vec<String>,
}
/// What can be replaced on a tag that is already declared: what it means, and nothing else.
///
/// No `--force`, unlike [`CampaignSetArgs`]. A codename is guarded because once a campaign
/// has one it is how the campaign is addressed, on every card and at every command line, so
/// replacing it silently breaks the way it is referred to. An annotation is prose written to
/// be revised and nothing addresses anything by it, so a guard would stand in front of the
/// command's whole purpose.
///
/// No rename. The tag *is* the key, so changing it means rewriting the Tags field of every
/// ticket carrying it. That is a migration, not a flag on `set`.
///
/// No `--clear`. An annotation is emptied with `--annotation ""`, which writes the same
/// placeholder a tag declared without one gets, so a second spelling would add nothing.
/// [`Clearable`] is a ticket's fields anyway, per [`SetArgs`].
///
/// `--annotation` is required, so a bare `worklane tags set <tag>` is a usage error rather
/// than a silent no-op, exactly as the group on [`CampaignSetArgs`] makes it for a campaign.
#[derive(clap::Args)]
pub struct TagSetArgs {
/// The tag to change, spelled the way it is declared
#[arg(value_parser = tag_value)]
pub tag: String,
/// What the tag means and when it is appropriate, replacing whatever it said before. Use
/// multiple flags for multiline annotations
#[arg(
short,
long,
required = true,
allow_hyphen_values = PROSE,
value_parser = annotation_line
)]
pub annotation: Vec<String>,
}
/// `ls` holds four filters, an output mode and nothing else, which is the boundary the
/// Rust Style rule in AGENTS.md names: two of the filters are adjacent `Option<String>`
/// values that a caller can swap silently, so the mode that joined them came as a
+50 -7
View File
@@ -66,6 +66,15 @@ pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
/// one where `ls --ids` answers the tickets.
pub const TAG_FLAGS: [&str; 1] = ["tag"];
/// Nested commands whose first argument is a tag the board already has.
///
/// `tags set` changes what a declared tag means, so the values it takes are exactly the
/// ones `worklane tags` prints. `tags add` is deliberately absent: the tag it takes is one
/// the board does not have yet, so offering the ones it does would offer exactly the values
/// it refuses. Which of the two a new tag positional belongs to is what
/// `no_tag_taking_option_is_missing` makes somebody decide.
pub const TAG_NESTED_COMMANDS: [(&str, &str); 1] = [("tags", "set")];
pub fn generate(shell: Shell, out: &mut dyn io::Write) -> io::Result<()> {
let mut command = crate::command::Cli::command();
clap_complete::generate(shell, &mut command, "worklane", out);
@@ -92,6 +101,11 @@ fn fish_dynamic() -> String {
.join("; or ");
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
let tag_flags = flag_list(&TAG_FLAGS);
let tag_nested = TAG_NESTED_COMMANDS
.iter()
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
.collect::<Vec<_>>()
.join("; or ");
let statuses = possible_values(Status::value_variants());
let shells = possible_values(Shell::value_variants());
let skills = SKILLS
@@ -182,6 +196,11 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
# worth reading: it says which spelling the board actually uses.
complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)'
# 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)'
# `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`
# has a `--clear` of its own that takes a field name, and clap already offers those.
@@ -351,6 +370,18 @@ mod tests {
assert_eq!(seen, 4, "expected assign, campaign show, campaign set and ls --campaign");
}
/// Commands whose tag positional names a tag that does not exist yet.
///
/// `tags add` declares a word the board has never carried, so completing it from
/// `worklane tags` would offer exactly the values the command refuses. Recorded rather
/// than skipped, so the *next* tag positional has to say which it is: `tags set` takes
/// a tag that is already declared and wants a rule in the fish block, and the test
/// below fails until it gets one or lands here.
///
/// In the test module because nothing outside it reads the list; the rule it encodes is
/// about what the fish block is missing, which is a test's question.
const TAG_NEW_COMMANDS: [(&str, &str); 1] = [("tags", "add")];
/// Tags have their own list because their values come from `worklane tags` rather than
/// from a listing of objects, so a second tag-taking option would need that rule and
/// not the campaign one.
@@ -363,19 +394,31 @@ mod tests {
}
seen += 1;
let name = path.join(" ");
let long = arg.get_long().unwrap_or_else(|| {
panic!(
"`worklane {name}` takes a tag as a positional, \
which the fish block has no rule for"
)
});
let Some(long) = arg.get_long() else {
let known = match path.as_slice() {
[parent, child] => {
let pair = (parent.as_str(), child.as_str());
TAG_NESTED_COMMANDS.contains(&pair) || TAG_NEW_COMMANDS.contains(&pair)
}
_ => false,
};
assert!(
known,
"`worklane {name}` takes a tag as a positional, so it belongs in \
TAG_NESTED_COMMANDS if the tag already exists and TAG_NEW_COMMANDS if it \
does not"
);
continue;
};
assert!(
TAG_FLAGS.contains(&long),
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
);
}
assert_eq!(seen, 1, "expected ls --tag");
assert_eq!(seen, 3, "expected ls --tag, tags add and tags set");
}
/// **Every rule naming an option has to say which command it belongs to.** A bare
+118 -3
View File
@@ -8,9 +8,10 @@ use std::path::Path;
use crate::campaign::*;
use crate::command::{
AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs,
RelateArgs, SetArgs,
RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
};
use crate::install;
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
use crate::util::*;
pub fn cmd_init(start: &Path) -> Result<()> {
@@ -33,6 +34,13 @@ pub fn cmd_init(start: &Path) -> Result<()> {
// campaigns, which is why `status_dirs()` is untouched.
fs::create_dir_all(campaigns_dir(&worklane_dir))?;
// The tag vocabulary, beside both for the same reason, and written empty rather than
// left for the first `tags add` to make. An empty file explains itself when it is
// opened, which is the point of the preamble, and a board that has one from the start
// has one file shape rather than two. `fs::write` and not `write_then_replace`: the
// directory was made three lines ago, so there is nothing here to truncate.
fs::write(tags_path(&worklane_dir), TagIndex::default().render())?;
println!("Initialized worklane in: {}", worklane_dir.display());
Ok(())
}
@@ -462,6 +470,7 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
/// mid-sentence so there is no capital to case.
const TICKET: &str = "ticket";
const CAMPAIGN: &str = "campaign";
const TAG: &str = "tag";
/// Write `content` over `path`, without ever leaving half a file behind.
///
@@ -863,12 +872,23 @@ fn apply(content: &mut String, changed: &mut Vec<&'static str>, field: &'static
}
fn report(fields: &[&str], title: &str, verb: &str) {
report_in(fields, title, Color::Green, verb)
}
/// The same, for a subject that is not a title.
///
/// Green means title, everywhere, so the one caller whose subject is a tag cannot use it:
/// a tag is drawn in a `TAG_COLORS` slot or it is drawn wrong, and green is deliberately
/// not one of them. The colour is passed in rather than decided here, which is the trade
/// `paint` makes with `color_text`, and it keeps the wording in one place so a tag reports
/// a no-op in the same words a ticket does.
fn report_in(fields: &[&str], title: &str, color: Color, verb: &str) {
if fields.is_empty() {
println!("No changes to '{}'", color_text(title, Color::Green));
println!("No changes to '{}'", color_text(title, color));
return;
}
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, Color::Green));
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, color));
}
pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
@@ -1239,6 +1259,101 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
Ok(())
}
/// Declare a tag, and what it means.
///
/// The counterpart of `cmd_tags`, which reports the vocabulary the tickets *carry*. This
/// writes the one the board *intends*, and the two are deliberately not kept in step: a
/// declaration tags nothing, so the file cannot be used to work out what is in use, and
/// `tags add` on a word no ticket carries is the normal case rather than a mistake.
///
/// **A tag already declared is refused rather than overwritten**, the way `add` refuses
/// nothing and `campaign set --codename` refuses a replacement without `--force`. An
/// annotation is the sentence a whole team files tickets against, so replacing one by
/// typing `add` twice is not something to do by accident. The refusal names the command
/// that does replace it, since that is the next thing the caller wants.
///
/// The whole file is re-rendered from the parsed vocabulary, so declaring a tag also
/// re-sorts the file and rewrites its preamble. That is why an unreadable file is an error
/// in `TagIndex::load` rather than an empty vocabulary: here, empty would mean erased.
pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let mut index = TagIndex::load(&worklane_dir)?;
if index.declared(&args.tag) {
return Err(anyhow!(
"Tag '{}' is already declared, so nothing was written. \
Use `worklane tags set` to change what it means",
args.tag
));
}
// Joined with a single newline, so an empty value is a paragraph break, exactly as it
// is for a description.
let annotation = trim_blank_ends(&args.annotation).join("\n");
index.declare(&args.tag, &annotation);
write_then_replace(
&worklane_dir,
&tags_path(&worklane_dir),
TAGS_FILE,
&index.render(),
TAG,
&args.tag,
)?;
// The tag in its own colour, which is the colour it is drawn in on every card and in
// every listing: `tag_color` is a pure function of the word.
println!("Declared tag: {}", color_text(&args.tag, tag_color(&args.tag)));
Ok(())
}
/// Replace what a declared tag means.
///
/// The other half of `tags add`, and the half `campaign` still lacks for its description,
/// 32e98ab. An annotation is the sentence a whole team files tickets against, so getting it
/// wrong once must not be permanent.
///
/// **A tag that is not declared is refused rather than declared here.** `add` and `set` are
/// a pair, each refusing what the other is for, so which of the two wrote a line is never a
/// question of which one happened to be typed. The refusal names the other command, the way
/// `add`'s names this one.
///
/// The no-op compares the rendered file rather than the annotation, which is what `apply`
/// does for a ticket: the file is the thing that would be written, so it is the thing worth
/// asking whether the write would change.
pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let mut index = TagIndex::load(&worklane_dir)?;
if !index.declared(&args.tag) {
return Err(anyhow!(
"No tag '{}' is declared, so nothing was written. \
Use `worklane tags add` to declare it",
args.tag
));
}
let original = index.render();
index.declare(&args.tag, &trim_blank_ends(&args.annotation).join("\n"));
let next = index.render();
let mut changed: Vec<&'static str> = Vec::new();
if original != next {
changed.push("annotation");
write_then_replace(
&worklane_dir,
&tags_path(&worklane_dir),
TAGS_FILE,
&next,
TAG,
&args.tag,
)?;
}
report_in(&changed, &args.tag, tag_color(&args.tag), "Updated");
Ok(())
}
/// Replace fields on a campaign that is already filed.
///
/// `cmd_set` for a campaign, and built out of the same parts: `set_title` for the heading,
+47 -1
View File
@@ -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
+19 -7
View File
@@ -7,6 +7,7 @@ mod command;
mod completions;
mod handlers;
mod install;
mod tag;
mod tui;
mod util;
@@ -78,10 +79,17 @@ fn main() -> Result<()> {
}
},
Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start),
Some(Command::Tags) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_tags(&worklane_dir)
}
// The bare form and `ls` are one arm: `worklane tags` was the listing before the
// group existed and the fish completion still calls it that way, so the two
// spellings cannot be allowed to drift into two behaviours.
Some(Command::Tags { command }) => match command {
None | Some(TagCommand::Ls) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_tags(&worklane_dir)
}
Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start),
Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start),
},
// No board either, for the reason `install-skill` has none: a completion script
// is generated from the clap definition and is the same wherever it is run.
Some(Command::Completions { shell }) => {
@@ -207,11 +215,15 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
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.
+312
View File
@@ -0,0 +1,312 @@
//! The tag vocabulary: which tags the board declares, and what each one means.
//!
//! One file, `.worklane/tags.md`, beside the status directories rather than among them,
//! for the reason the campaigns directory sits there: a tag has no status. One section
//! per tag, the tag as the heading and its annotation as the prose under it, so the file
//! reads as a document to whoever opens it and parses by heading to the CLI.
//!
//! **Declaring a tag tags no ticket, and tagging a ticket declares nothing.** This is a
//! vocabulary and not an index of what carries what: the counts stay derived from the
//! status directories, where `cmd_tags` already reads them. So the file and the board can
//! disagree, and that disagreement is the point — a tag carried but never declared is a
//! word nobody agreed to, which is what `campaign` and `campaigns` on this board were.
//!
//! Unlike a campaign, a tag has no uuid and no file of its own. It *is* its name, which is
//! what `ls --tag` matches whole and case sensitively, so the name is the key here and
//! there is nothing to resolve by prefix.
use anyhow::{Result, anyhow};
use std::collections::BTreeMap;
use std::fs;
use std::path::{Path, PathBuf};
use crate::util::trim_blank_ends;
/// The vocabulary file, beside the status directories rather than among them.
pub const TAGS_FILE: &str = "tags.md";
pub fn tags_path(worklane_dir: &Path) -> PathBuf {
worklane_dir.join(TAGS_FILE)
}
/// What one tag's heading looks like, and therefore what an annotation may not start a
/// line with.
///
/// Public so the `--annotation` parser refuses the one line that would split a section,
/// rather than carrying its own copy of the spelling. Two places knowing what a heading
/// is, is how the file comes to be written in a shape it cannot be read back in.
pub const SECTION: &str = "## ";
/// What a tag declared with nothing to say about it writes.
///
/// A placeholder rather than an empty section, for the reason `add` writes one into an
/// empty Description: a heading with nothing under it reads as a file that failed to
/// write, and the round trip has nothing to be right about.
pub const NO_ANNOTATION: &str = "_No annotation provided._";
/// The heading the file opens with. Not a tag: [`tag_heading`] only reads level two.
const TITLE: &str = "# Tags";
/// What the file says for itself, for whoever opens it rather than for the parser.
///
/// Re-rendered on every write, so it is present whether `init` made the file or
/// `tags add` did. It says what declaring does and does not do, because the file's one
/// real trap is reading it as the list of tags in use.
const PREAMBLE: &str = "\
What each tag on this board means, and when it is appropriate to reach for it. Declaring a
tag here tags nothing: the counts come from the tickets themselves, and `worklane tags` is
what reports them. Written by `worklane tags`, not by hand.";
/// The tag a level-two heading names, or nothing for any other line.
///
/// Exactly two hashes. A `### ` line inside an annotation is prose about the tag it sits
/// under and not the start of another one, which a bare `strip_prefix` would read as a tag
/// called `# something`.
fn tag_heading(line: &str) -> Option<&str> {
let rest = line.strip_prefix(SECTION)?;
match rest.starts_with('#') {
true => None,
false => Some(rest.trim()),
}
}
/// The board's declared tags, each with what it means.
///
/// A `BTreeMap` rather than a `Vec`: the order is alphabetical by byte, which is the order
/// `cmd_tags` already prints in, so `Bug` and `bug` stay two entries and land next to each
/// other. Near-duplicates being adjacent is the property the whole file is for.
///
/// An annotation of `""` is a tag declared with nothing said about it, which is why the
/// placeholder is a rendering detail rather than a value anything holds.
#[derive(Default)]
pub struct TagIndex {
tags: BTreeMap<String, String>,
}
impl TagIndex {
/// The vocabulary as the file declares it.
///
/// A missing file is an empty vocabulary and not an error: every board made before this
/// existed has none, and refusing there would mean a `worklane init` over a live board
/// just to get a file.
///
/// An *unreadable* file is an error, which is the opposite of what [`CampaignIndex`]
/// does with its directory, and deliberately. The whole file is re-rendered on every
/// write, so treating one that is there as empty would erase every tag in it on the
/// next `tags add`. A campaign index that comes back empty loses a label on a card;
/// this one would lose the file.
///
/// [`CampaignIndex`]: crate::campaign::CampaignIndex
pub fn load(worklane_dir: &Path) -> Result<Self> {
let path = tags_path(worklane_dir);
if !path.exists() {
return Ok(Self::default());
}
let content = fs::read_to_string(&path).map_err(|e| {
anyhow!("Could not read the tag vocabulary at {}: {}", path.display(), e)
})?;
Ok(Self::parse(&content))
}
/// The vocabulary out of the file's text.
///
/// Everything above the first tag heading is prose for whoever opens the file and is
/// dropped: the title, the preamble, and anything else that ended up there. A heading
/// with no tag in it starts nothing, and the lines under it belong to no tag, so a
/// damaged file loses that section rather than attaching it to the tag above.
pub fn parse(content: &str) -> Self {
let mut tags = BTreeMap::new();
let mut open: Option<(String, Vec<String>)> = None;
for line in content.lines() {
match tag_heading(line) {
Some(tag) => {
if let Some((held, body)) = open.take() {
tags.insert(held, annotation(&body));
}
if !tag.is_empty() {
open = Some((tag.to_string(), Vec::new()));
}
}
None => {
if let Some((_, body)) = &mut open {
body.push(line.to_string());
}
}
}
}
if let Some((held, body)) = open {
tags.insert(held, annotation(&body));
}
Self { tags }
}
/// Whether the file already declares this tag, matched whole and case sensitively, the
/// way `ls --tag` matches it.
pub fn declared(&self, tag: &str) -> bool {
self.tags.contains_key(tag)
}
/// Declare `tag`, or replace what it means.
///
/// One writer for both, because the file holds one section per tag either way and the
/// question of whether a caller may overwrite is the caller's: `tags add` refuses a tag
/// already declared, and `tags set` refuses one that is not.
pub fn declare(&mut self, tag: &str, annotation: &str) {
self.tags.insert(tag.to_string(), annotation.to_string());
}
/// The whole file, rendered from the whole vocabulary.
///
/// Every write goes through here rather than splicing one section in place, which is
/// what keeps the file canonical: alphabetical, one blank line between sections, and
/// the preamble present however the file came to exist. The cost is that nothing
/// hand-written above the first heading survives a write, which is the bargain every
/// file under `.worklane/` already makes — the CLI is its only writer.
pub fn render(&self) -> String {
let mut out = format!("{TITLE}\n\n{PREAMBLE}\n");
for (tag, annotation) in &self.tags {
let body = match annotation.is_empty() {
true => NO_ANNOTATION,
false => annotation,
};
out.push_str(&format!("\n{SECTION}{tag}\n{body}\n"));
}
out
}
}
/// One section's prose, with the blank lines around it dropped and the placeholder read
/// back as nothing.
///
/// Through `trim_blank_ends`, the same function that decides where a ticket's description
/// starts and ends, so a blank line inside an annotation is kept and one at either end is
/// not.
fn annotation(body: &[String]) -> String {
let text = trim_blank_ends(body).join("\n");
match text == NO_ANNOTATION {
true => String::new(),
false => text,
}
}
#[cfg(test)]
mod tests {
use super::*;
/// What a tag holds, read back out of the file it was written into. The round trip is
/// the property that matters: nothing else keeps the writer and the parser agreeing on
/// what a section is.
fn round_trip(tag: &str, annotation: &str) -> String {
let mut index = TagIndex::default();
index.declare(tag, annotation);
let read = TagIndex::parse(&index.render());
read.tags
.get(tag)
.cloned()
.expect("the tag did not survive the round trip")
}
#[test]
fn an_annotation_survives_the_round_trip() {
assert_eq!(
round_trip("bug", "Something the binary does wrong."),
"Something the binary does wrong."
);
}
/// A blank line inside an annotation is a paragraph break and is kept, which is what
/// `trim_blank_ends` is doing here rather than a blanket trim.
#[test]
fn a_paragraph_break_inside_an_annotation_is_kept() {
assert_eq!(round_trip("bug", "One.\n\nTwo."), "One.\n\nTwo.");
}
/// A tag declared with nothing to say writes the placeholder and reads back as nothing,
/// so the file never holds a heading with a blank under it and nothing ever holds the
/// placeholder as if it were prose.
#[test]
fn a_tag_with_no_annotation_writes_the_placeholder_and_reads_back_empty() {
let mut index = TagIndex::default();
index.declare("cli", "");
let rendered = index.render();
assert!(rendered.contains(NO_ANNOTATION), "{rendered}");
assert_eq!(TagIndex::parse(&rendered).tags["cli"], "");
}
/// Byte order, so `Bug` and `bug` are two tags and sit next to each other. The same
/// order `tags` prints in, and the reason the file is worth reading at all: a
/// near-duplicate is spotted by being adjacent to what it duplicates.
#[test]
fn the_file_is_alphabetical_and_keeps_case_apart() {
let mut index = TagIndex::default();
for tag in ["tui", "bug", "Bug", "cli"] {
index.declare(tag, "");
}
let rendered = index.render();
let headings: Vec<&str> = rendered.lines().filter_map(tag_heading).collect();
assert_eq!(headings, vec!["Bug", "bug", "cli", "tui"]);
}
/// Everything above the first heading is for whoever opens the file. The preamble says
/// `## ` nowhere, but a parser that took the title for a tag would declare one called
/// `Tags` on the next write.
#[test]
fn the_prose_above_the_first_heading_declares_nothing() {
let index = TagIndex::parse(&TagIndex::default().render());
assert!(index.tags.is_empty(), "the preamble declared a tag");
}
/// A deeper heading is prose about the tag it sits under. `strip_prefix` alone read it
/// as a tag called `# whatever`, which then became a real section on the next write.
#[test]
fn a_deeper_heading_inside_an_annotation_is_not_a_tag() {
let index = TagIndex::parse("# Tags\n\n## bug\nProse.\n\n### An aside\nMore prose.\n");
assert_eq!(index.tags.len(), 1, "a sub-heading was read as a tag");
assert_eq!(index.tags["bug"], "Prose.\n\n### An aside\nMore prose.");
}
/// A heading naming nothing starts no section, and takes the lines under it with it
/// rather than attaching them to the tag above.
#[test]
fn an_empty_heading_declares_nothing_and_swallows_its_own_body() {
let index = TagIndex::parse("## bug\nProse.\n\n## \nOrphaned.\n");
assert_eq!(index.tags.len(), 1);
assert_eq!(index.tags["bug"], "Prose.");
}
/// A board that never had the file has an empty vocabulary rather than an error: every
/// board made before this existed is in that state.
#[test]
fn a_board_with_no_file_has_no_tags() {
let dir = tempfile::tempdir().unwrap();
assert!(TagIndex::load(dir.path()).unwrap().tags.is_empty());
}
/// And a file that is there but cannot be read is an error, not an empty vocabulary.
/// The whole file is re-rendered on every write, so empty here would mean erased on the
/// next `tags add`.
#[test]
fn a_file_that_cannot_be_read_is_an_error_rather_than_an_empty_vocabulary() {
let dir = tempfile::tempdir().unwrap();
// A directory where the file should be: `read_to_string` fails on it, which a
// missing file does not, so this is the path the error is actually for.
fs::create_dir(tags_path(dir.path())).unwrap();
assert!(TagIndex::load(dir.path()).is_err());
}
}
+881 -49
View File
File diff suppressed because it is too large Load Diff
+26 -11
View File
@@ -1776,23 +1776,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
+359
View File
@@ -4,6 +4,11 @@
//! tags exist, which is the question a grooming sweep starts from. So the properties
//! 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.
use assert_cmd::Command;
use assert_fs::TempDir;
@@ -175,3 +180,357 @@ fn tags_skips_a_missing_status_directory() {
assert_eq!(tags(&temp), vec!["bug\t1"]);
}
// ------------------------------------------------------------- the vocabulary --
fn vocabulary(temp: &TempDir) -> String {
fs::read_to_string(temp.path().join(".worklane").join("tags.md")).unwrap()
}
/// The section a tag holds in the file, heading excluded, or `None` when it is not
/// declared. Cut out of the file rather than asserted against a whole rendering, so a
/// change to the preamble does not fail every test here.
fn declared(temp: &TempDir, tag: &str) -> Option<String> {
let file = vocabulary(temp);
let (_, rest) = file.split_once(&format!("\n## {tag}\n"))?;
let body = match rest.split_once("\n## ") {
Some((body, _)) => body,
None => rest,
};
Some(body.trim().to_string())
}
/// The declaration lands in the file, with the annotation under it.
#[test]
fn tags_add_declares_a_tag_with_what_it_means() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(
&temp,
&[
"tags",
"add",
"bug",
"--annotation",
"Something the binary does wrong.",
],
);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something the binary does wrong."));
}
/// Several flags are several lines, and an empty one is a paragraph break, the way a
/// description is written.
#[test]
fn an_annotation_takes_several_lines_and_a_paragraph_break() {
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!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
}
/// A tag can be declared with nothing said about it. The word being agreed on is worth
/// recording before anyone has written the sentence.
#[test]
fn a_tag_can_be_declared_without_an_annotation() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(&temp, &["tags", "add", "cli"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert_eq!(declared(&temp, "cli").as_deref(), Some("_No annotation provided._"));
}
/// Refused rather than overwritten, and the refusal names what does overwrite it: an
/// annotation is the sentence a team files tickets against, not something to replace by
/// typing `add` twice.
#[test]
fn declaring_a_tag_twice_is_refused_and_names_the_command_that_replaces_it() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
let out = run(&temp, &["tags", "add", "bug", "-a", "A different sentence."]);
assert!(!out.status.success());
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("tags set"), "{stderr}");
assert_eq!(declared(&temp, "bug").as_deref(), Some("The first sentence."));
}
/// A comma is what separates one tag from the next, so a value carrying one could never be
/// matched by `--tag`. Refused at parse, with nothing written.
#[test]
fn a_tag_the_filter_could_never_match_is_refused() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
for value in ["bug,cli", ""] {
let out = run(&temp, &["tags", "add", value]);
assert!(!out.status.success(), "'{value}' was accepted");
}
// Nothing was written on the way past, not even the empty file.
assert!(!temp.path().join(".worklane").join("tags.md").exists());
}
/// Surrounding space is trimmed rather than refused, because a ticket's Tags field is read
/// that way too: ` bug ` on a card is the tag `bug`, and the vocabulary has to agree.
#[test]
fn a_padded_tag_is_declared_under_its_trimmed_name() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", " bug "]);
assert!(declared(&temp, "bug").is_some(), "{}", vocabulary(&temp));
}
/// An annotation line that would be read back as a heading is refused, since it would split
/// the section and declare whatever followed it.
#[test]
fn an_annotation_that_would_read_as_a_heading_is_refused() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
let out = run(&temp, &["tags", "add", "bug", "-a", "## cli"]);
assert!(!out.status.success());
assert!(!temp.path().join(".worklane").join("tags.md").exists());
}
/// The file is made on demand, the way `campaign add` makes the campaigns directory: a board
/// that predates the vocabulary must not need `worklane init` run over it.
#[test]
fn the_file_is_created_on_a_board_that_predates_it() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
assert!(!temp.path().join(".worklane").join("tags.md").exists());
run(&temp, &["tags", "add", "bug"]);
assert!(declared(&temp, "bug").is_some());
}
/// `init` writes it, so a new board has one file shape rather than two.
#[test]
fn init_writes_the_vocabulary_beside_the_status_directories() {
let temp = TempDir::new().unwrap();
let out = run(&temp, &["init"]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let file = vocabulary(&temp);
assert!(file.starts_with("# Tags"), "{file}");
// The preamble and nothing else: a new board declares no tags.
assert!(!file.contains("\n## "), "{file}");
}
/// A second declaration keeps the first, and the file stays alphabetical: the whole file is
/// re-rendered, so this is the test that the re-render is not a truncation.
#[test]
fn declaring_a_tag_leaves_the_others_alone_and_keeps_the_order() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "tui", "-a", "The board view."]);
run(&temp, &["tags", "add", "bug", "-a", "Something wrong."]);
assert_eq!(declared(&temp, "tui").as_deref(), Some("The board view."));
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something wrong."));
let file = vocabulary(&temp);
assert!(file.find("## bug").unwrap() < file.find("## tui").unwrap(), "{file}");
}
/// A file that is there and cannot be read stops the write rather than being taken for an
/// empty vocabulary. Empty would mean erased, since every declaration re-renders the file.
#[test]
fn a_vocabulary_that_cannot_be_read_is_refused_rather_than_replaced() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
// A directory where the file should be: `read_to_string` fails on it, which a missing
// file does not.
fs::create_dir(worklane.join("tags.md")).unwrap();
let out = run(&temp, &["tags", "add", "bug"]);
assert!(!out.status.success());
assert!(worklane.join("tags.md").is_dir(), "the file was replaced");
// And nothing was staged and left behind.
let stray: Vec<_> = fs::read_dir(&worklane)
.unwrap()
.filter_map(|e| e.ok())
.filter(|e| e.file_name().to_string_lossy().starts_with(".wl-"))
.collect();
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.
#[test]
fn a_declared_tag_is_not_a_carried_one() {
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"]);
}
/// The bare form is the listing, byte for byte, because the shipped fish completion calls it
/// that way to fill in `ls --tag`. `tags ls` is the same thing spelled as a group.
#[test]
fn the_bare_form_and_ls_are_the_same_listing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
run(&temp, &["tags", "add", "chore"]);
let bare = run(&temp, &["tags"]);
let group = run(&temp, &["tags", "ls"]);
assert!(bare.status.success());
assert_eq!(bare.stdout, group.stdout);
assert_eq!(String::from_utf8_lossy(&bare.stdout), "bug\t1\ncli\t1\n");
}
// -------------------------------------------------- changing what a tag means --
/// The replacement lands, and replaces rather than appends.
#[test]
fn tags_set_replaces_what_a_tag_means() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
let out = run(&temp, &["tags", "set", "bug", "-a", "The second sentence."]);
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
assert_eq!(declared(&temp, "bug").as_deref(), Some("The second sentence."));
assert!(!vocabulary(&temp).contains("first"), "the old annotation survived");
}
/// Paragraph breaks survive the round trip, which is the whole difference between an
/// annotation and a one-line description of a tag.
#[test]
fn a_multiline_annotation_survives_being_set() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug"]);
run(
&temp,
&[
"tags",
"set",
"bug",
"-a",
"What it is.",
"-a",
"",
"-a",
"When to use it.",
],
);
assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
}
/// Set to what it already says, nothing is written and the command says so, the way `set`
/// and `chown` report a field that already holds the value.
#[test]
fn setting_an_annotation_to_what_it_already_says_writes_nothing() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
let before = fs::metadata(temp.path().join(".worklane").join("tags.md"))
.unwrap()
.modified()
.unwrap();
let out = run(&temp, &["tags", "set", "bug", "-a", "The sentence."]);
assert!(out.status.success());
assert!(String::from_utf8_lossy(&out.stdout).contains("No changes"), "{out:?}");
let after = fs::metadata(temp.path().join(".worklane").join("tags.md"))
.unwrap()
.modified()
.unwrap();
assert_eq!(before, after, "the file was rewritten for a no-op");
}
/// `add` and `set` are a pair, each refusing what the other is for, so the refusal names
/// the other command rather than leaving it to be found.
#[test]
fn setting_a_tag_that_is_not_declared_is_refused_and_names_add() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug"]);
let out = run(&temp, &["tags", "set", "cli", "-a", "Anything."]);
assert!(!out.status.success());
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("tags add"), "{stderr}");
assert!(declared(&temp, "cli").is_none(), "the tag was declared by set");
}
/// A bare `tags set <tag>` is a usage error. Nothing to write is a mistake in the call, not
/// a command that quietly does nothing.
#[test]
fn setting_nothing_is_a_usage_error() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
let out = run(&temp, &["tags", "set", "bug"]);
assert_eq!(out.status.code(), Some(2), "{out:?}");
assert_eq!(declared(&temp, "bug").as_deref(), Some("The sentence."));
}
/// An annotation can be emptied back to the placeholder, which is the state a tag declared
/// without one is already in. That is why there is no `--clear`.
#[test]
fn an_annotation_can_be_emptied_back_to_the_placeholder() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
run(&temp, &["tags", "set", "bug", "-a", ""]);
assert_eq!(declared(&temp, "bug").as_deref(), Some("_No annotation provided._"));
}
/// The other tags keep their sections, since the whole file is re-rendered on every write.
#[test]
fn setting_one_annotation_leaves_the_others_alone() {
let temp = TempDir::new().unwrap();
setup_worklane(&temp);
run(&temp, &["tags", "add", "bug", "-a", "About bugs."]);
run(&temp, &["tags", "add", "tui", "-a", "About the board."]);
run(&temp, &["tags", "set", "bug", "-a", "Rewritten."]);
assert_eq!(declared(&temp, "bug").as_deref(), Some("Rewritten."));
assert_eq!(declared(&temp, "tui").as_deref(), Some("About the board."));
}